pkgmgr:state

pkgmgr:state@0.0.0

A document is written as one of namespacesConfig, pkgsConfig.

namespacesConfig

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in metadata.documentRoots, never declared
namespaceslist[string]NoThe label of each namespace the store declares, in the order they were added. A label is also the name of the directory the namespace's packages sit in under the store root. Absent or empty for a store that declares none

pkgsConfig

FieldTypeRequiredDefaultDescription
schemaVersionversionYesThe version of this document's schema that this document was written under -- granted by the meta-schema to every definition named in metadata.documentRoots, never declared
pkgsdict[string, dict[string, pkgVersionContainer]]NoThe packages the store holds: keyed by namespace label, then by package label, each package with its entries under both of the keys it may be reached by. Absent or empty for a store that holds none

pkgConfigItem

FieldTypeRequiredDefaultDescription
labelstringYesThe label the package is indexed under in its namespace. The same as name for a registered artifact or schema; pkg add and pkg update let the two differ
namestringYesThe package's name: the second segment of its coordinate for a registered artifact or schema, and the directory its versions sit in under its namespace
sourceUriuriNoWhere the package comes from, for an entry that points somewhere other than the store holding it. An artifact the store holds carries none: path locates it relative to the store root, and an absolute file URI would name one machine's checkout of the store.
typeenum one of local, gitYesHow the entry's content is held. local is a file or a directory tree the store keeps; git is a repository cloned from sourceUri and checked out as a git submodule at the entry's place
pathpathYesWhere the entry's content is, written with forward slashes: the artifact file or the version's directory, relative to the root of the store holding it. For a registered schema, the source document the stored copy was taken from, relative to the directory holding the store where it sits inside it
versionversionNoThe version this entry was produced at, in full. An entry reached by its sha is reached without a version key at all, and a version key renders to the store's shape rather than to the whole version, so an entry that does not carry its own version has nowhere to keep the rest of it.
shastringNoThe source state this entry was produced from, where it was produced from one. A version says what was built; a sha says which source it was built out of, which is what makes two entries at one version distinguishable and what a build cache looks up.
shaKindenum one of commit, gittree, tree, builtNoHow the sha was arrived at: commit is a clean checkout's own commit, gittree a checkout carrying uncommitted changes, tree a directory that is not a git repository at all, and built a digest of one of those together with the other states the artifact was built from, which names no source on its own. It does not change a lookup, since a reader computes the key the same way whichever it is; it is recorded because a gittree entry is a build of source that no commit holds, which is what someone reading a surprising cache hit needs to see.
digeststringNoThe sha256 of the file path names, in hexadecimal, where the entry is one file a store holds: what a reader that fetched the file from somewhere else checks it against. sha says which source an artifact was built from and nothing about its bytes. Absent from an entry that is a directory, from one whose path names a source document, and from one written before the field existed; an entry carrying none is not checked.
registeredAtdatetimeNoWhen this entry was written into the index. A sha key is content rather than a clock, so it puts two builds of one version in no order at all; this is the order retention reads -- keep the most recent N, or clear what predates a cutoff. Optional because an entry written before the field existed carries none, and an entry carrying none is the oldest there is.
releaseNotesreleaseNotesNoWhat the release this entry belongs to changed, and what a deployer has to know before taking it, as the release drafted them for its review. Every entry one release files carries the same notes, so a consumer holding any of them holds the release's notes, and one comparing two versions reads the notes of each version between them. Absent from an entry no release drafted notes for: a build, a development registration, or a release published before the field existed.
clientNotesclientNotesNoWhat the release this entry belongs to means for a client, where the entry is something a client receives and the release is one chosen for them: drafted when the release goes public, from the release's own notes and those of everything it bundles, back to the last release clients received. Where releaseNotes is written for the people who build the tree and names their pull requests, this names nothing a client does not use. Absent from an entry clients do not receive, and from a release that has not gone public.
dependencieslist[releaseDependency]NoWhat the release this entry belongs to was released against: each library and schema its repository resolved, other than tooling, at the released version whose source matches what resolved. Every entry one release files carries the same list. Absent from an entry that is not a release, and from a release published before the field existed; an empty list is a release that depends on nothing.
audienceenum one of public, internalNoWho the release this entry belongs to is for: internal is a release the tree cut for its own repositories, public one chosen for clients. Every entry one release files carries the same audience, and promoting a release rewrites it on each of them. It is about the release, where a module's own audience is about the module: a public module in an internal release has not been shipped to anybody. Absent from an entry that is not a release, and from a release published before the field existed, which is read as internal.
executableFormenum one of bundled, compiledNoWhat an executable entry is, as the build that made it says: bundled is the interpreter and the application's bytecode put together, which anybody holding it can read back into source and which is therefore never handed to a client; compiled is the application translated to native code, the only form a client is handed. Two entries of one application at the same commits, version and platform differ by this alone, so a reader that cares which it holds asks it rather than the name. Absent from an entry that is no executable, and from one filed before the field existed, which is read as bundled.
signedWithenum one of authenticode, sigstoreNoHow an executable a client is handed was signed before it was filed, so its digest is of the signed artifact: authenticode, a Windows signature inside each signed file, checked by the system that runs it; sigstore, a detached Sigstore bundle filed inside the artifact beside the executable it signs, as <executable>.sigstore.json. Absent from an entry that was not signed, which no executable a client is handed may be.
treeShastringNoThe commit of the tree an executable was built in, beside sha, the commit of its own repository: a build is of one source only where every platform's was made at the same pair, so an executable a release of the tree is handed records both and is checked against both. Absent from an entry that was not built in a tree, which is every entry but a compiled executable a client is handed.
languageVersionsversionRangeNoThe versions of its language a repo adapter is for, as the adapter states them: a version, a list read as the span from its lowest item to its highest, or bounds joined by a comma. Recorded by the release that files the entry, on a language core and on each adapter that configures one, so a reader choosing among releases can tell which is for a repository without unpacking any of them. Absent from an entry that is no adapter's, from a build, and from a release published before the field existed; an entry carrying none is for every version.
readmestringNoThe README at the root of the module this entry was released from, as the released commit holds it: the module's client documentation, which its archive carries and which a reader holding only the catalog reaches by the module's coordinate. A release records it on the entry of each module declared public and on no other entry it files, so it is the module's where the notes are the release's. A relative link in it is followed from the module's root and names a file inside the module. Absent from an entry of an internal module, from one that is not a release, and from a release published before the field existed.

releaseDependency

FieldTypeRequiredDefaultDescription
coordinatepinnedCoordinateYesThe dependency, pinned: namespace:name@version
shastringNoThe commit a library dependency was released from, which is what the releasing repository's lock resolved it to
digeststringNoThe sha256 of a schema dependency's released document, which is what the releasing repository generated from

releaseNotes

FieldTypeRequiredDefaultDescription
sincestringNoThe commit the previous release was cut from, which these notes run from. Absent for a first release, whose notes run over the whole history reachable from the released commit.
changeslist[releaseChange]No[]What the release changed, one item per pull request merged since the previous release
considerationslist[releaseConsideration]No[]What a deployer has to know before taking the release, each as the pull request that raised it stated it. A pull request that stated none contributes nothing.

releaseChange

FieldTypeRequiredDefaultDescription
pullRequestintegerYesThe number of the pull request that made the change, in the released repository
urluriNoWhere that pull request is
summarystringYesWhat changed, in one line

releaseConsideration

FieldTypeRequiredDefaultDescription
pullRequestintegerYesThe number of the pull request whose Release considerations section raised this, in the released repository
urluriNoWhere that pull request is
summarystringYesWhat a deployer has to know, as the pull request stated it
actionstringNo""What to do about it, where the pull request said; empty when the item is a fact to be aware of rather than a step

clientNotes

FieldTypeRequiredDefaultDescription
sincestringNoThe version of the last release clients received, which these notes run from: every release between it and this one is covered, since a client saw none of them. Absent for the first release clients receive.
changeslist[clientChange]No[]What a client can observe changed, in the terms of what they use
considerationslist[clientConsideration]No[]What a client has to act on before or after taking the release

clientChange

FieldTypeRequiredDefaultDescription
summarystringYesWhat changed for a client, in one line

clientConsideration

FieldTypeRequiredDefaultDescription
summarystringYesWhat changed that a client has to act on: a renamed option, a changed default, a removed command
actionstringNo""What to do about it

sourceSha

FieldTypeRequiredDefaultDescription
shastringYesThe key the source state resolved to: a commit sha for a clean checkout, and otherwise a digest, as kind says
kindenum one of commit, gittree, tree, builtYesHow the sha was arrived at: commit is a clean checkout's own commit, gittree a checkout carrying uncommitted changes, tree a directory that is not a git repository at all, and built a digest of one of those together with the other states an artifact was built from. It travels with the key so an entry built from uncommitted source says so; it never changes a lookup, a reader computing the key the same way whichever it is.

pkgVersionContainer

FieldTypeRequiredDefaultDescription
lateststringNoWhich of versions is current. A key rather than a version: version keys render to the store's shape, so a latest typed as a version had to guess that shape and named nothing when it guessed wrong. Absent where a package has no version-addressed entry at all.
versionsdict[string, pkgConfigItem]YesEntries keyed by version, for a package addressed by its coordinate. Empty where a package is only ever asked for by source state, which is what a catalog of builds is.
shasdict[string, pkgConfigItem]NoEntries keyed by the source state each was produced from, for a package whose artifacts differ within one version.

listedVersion

FieldTypeRequiredDefaultDescription
versionstringYesThe version key this entry is stored under, in the store's own shape
entrypkgConfigItemYesThe stored record itself, as the index holds it

listedSha

FieldTypeRequiredDefaultDescription
shastringYesThe source state key this entry is stored under
entrypkgConfigItemYesThe stored record itself, as the index holds it

listedPkg

FieldTypeRequiredDefaultDescription
storestringYesThe label of the store this package was found in. Carried on the record as well as on the group above it: once a result spans stores, a package lifted out of the tree that does not say where it came from cannot be resolved back to one.
namespacestringYesThe namespace this package is registered under
namestringYesThe name the package is stored under, which is the second segment of its coordinate
lateststringNoWhich version key the store calls current, absent where the package has no version-addressed entry
versionslist[listedVersion]No[]The stored records, present only for a listing that asked for values. Empty otherwise, which is the listing that answers with identifiers alone.
shaslist[listedSha]No[]The source-addressed records, present only for a listing that asked for them. A package registered only by coordinate has none.

listedNamespace

FieldTypeRequiredDefaultDescription
namespacestringYesThe namespace label
pkgslist[listedPkg]No[]The packages registered under it, in name order. Empty for a namespace that holds none, which a namespace listing still reports.

listedStore

FieldTypeRequiredDefaultDescription
storestringYesThe label the store was selected by -- local for the repository the command ran in, otherwise the label its configuration gives the store
rootpathYesThe directory the store's uri resolved to
namespaceslist[listedNamespace]No[]What was found there, in namespace order