Cog Packages
A cog is Verum's unit of package distribution. The package CLI publishes
source archives and metadata to a configured HTTP registry. Compiled .vbca
archives have a separate precompilation workflow.
The registry service and its integration with the compiler are under development. The client has local publication checks, but a successful dry run does not establish that a registry can store, serve, and build the package. Complete publication-to-installation acceptance, durable release storage, and consumer feature resolution remain limitations of the platform.
Configure a registry
Set the registry base URL explicitly in the project's Verum.toml:
[registry]
index = "https://registry.example.com"
Replace the example URL with your registry's address. Despite the field name,
this is the base URL: package operations append /api/v1 and their endpoint.
Do not include /api/v1 in index.
verum package publish, search, and install use this setting. An invalid
project manifest causes an error instead of silently selecting another registry.
Implicit defaults differ between manifest-backed and projectless operations, so
an explicit URL is required for a predictable workflow.
The local cog registry is a separate catalogue of
verification manifests, with its own verum cog-registry commands.
Publishing
Run these commands from the cog project:
verum package publish --dry-run
verum package publish
A dry run validates the manifest and publication dependencies, creates the source archive, calculates its SHA-256 digest, and checks the publication metadata and size limits. It does not upload or require an authentication token. It removes the temporary archive after validation.
Archive creation checks completion of the tar stream, the gzip stream and the final output flush. An error at any of these stages fails the command before upload, including during a dry run.
A real upload reads VERUM_REGISTRY_TOKEN or the package command's credentials
file and sends a bearer-authenticated request. Supply the token through your
shell or CI secret configuration. The package command has no login subcommand.
Publishing from a Git working tree with uncommitted changes is refused unless
--allow-dirty is supplied. A dry run permits a dirty tree. Compilation, tests,
linting, and compatibility with an earlier release are separate checks; the
publish command does not perform them.
The client accepts success only when the registry returns a JSON receipt whose name, version, and archive checksum match the request. Publication redirects are refused. A matching receipt acknowledges those bytes and coordinates; it does not certify source correctness or prove durable storage.
Source archive
The package command creates a gzip-compressed tar archive containing:
Verum.toml
src/ # files from the source directory, when present
README.md # first available README variant, when present
LICENSE # first available LICENSE variant, when present
The manifest entry is always Verum.toml, including for projects using the
legacy lowercase filename. Compiled bytecode, generated API documentation and
proof certificates are not generated by this command.
Publication metadata carries identity, descriptive fields, dependencies, features, and the SHA-256 checksum of the exact archive bytes. The default client limits are 256 KiB of serialized metadata and 64 MiB of archive data.
Source publication accepts no signature, proof, profile, IPFS or derived-artifact claims. The package command still discovers existing signing keys automatically; if a key produces a signature, publication and its dry run fail with an unsupported-claims error. Signed publication requires further integration.
Dependencies
Entries in [dependencies] can use a version requirement or a detailed declaration:
[dependencies]
codec = "^1.4"
transport = { version = "2.0", features = ["tls"], optional = true, default-features = false }
Publication metadata projects the normal [dependencies] table; development
and build dependency tables remain in the archived manifest. Their publication
validation and consumer handling are not yet integrated. Publishing preserves
features, optional, and default-features, including
explicit empty lists and false values. default_features is also accepted in
the manifest. A detailed published dependency must contain an explicit valid
version requirement; an explicit "*" is allowed, but a missing version is an
error.
Local and Git sources can be declared for development:
[dependencies]
utils = { path = "../utils" }
parser = { git = "https://example.com/team/parser.git", rev = "release-branch" }
The source publication format cannot represent path, git, branch, tag,
or rev. Publishing refuses a dependency containing any of them, even when it
also supplies a version. Replace development sources with registry dependencies
explicitly before publishing; there is no automatic path-to-version rewrite.
Unknown detailed dependency fields are errors during manifest loading. Fields
such as ipfs, registry, package, and workspace are not accepted by the
CLI dependency schema.
Preserving feature declarations in publication metadata does not establish complete feature activation in the consumer. Optional dependencies, default features, and transitive feature unification still need end-to-end integration. See the manifest reference for the project schema.
Search and install
verum package search codec --limit 10
verum package install codec --version 1.4.2
Use an exact version with --version. Although the argument is parsed as a
version requirement, this command passes the supplied text to the version
endpoint; it does not select a matching release from a range. Omitting the flag
uses the registry's latest-version endpoint.
Installation obtains metadata and the archive from the configured registry,
checks the archive checksum, and verifies a signature if metadata includes one.
It then updates the project dependency and lockfile. The archive cache is under
the operating system's cache directory, in verum/cogs.
Installation of one requested package does not establish a resolved, verified transitive dependency closure. Run the project's build and tests after changing its dependencies; a successful download alone is not build acceptance.
Trust model
A checksum comparison establishes agreement with the retrieved metadata. It does not independently authenticate the publisher. Signature verification, when metadata includes a signature, is separate from deciding which publisher keys to trust. There is no package option that requires a trusted publisher or a specified verification level.
Before downloading an archive, installation requests a vulnerability report from the configured registry for the selected cog and version. An unsuccessful HTTP response, transport failure, malformed report, or report naming a different cog or version stops installation. These failures occur before downloading or caching an archive and before changing the project manifest or lockfile.
A valid report containing advisories produces warnings and installation continues. "No known vulnerabilities" is printed only for a successful response with a valid, matching, empty report. It describes the registry's report; it does not establish that the package is safe.
See check_vulnerabilities
for report validation and
install_from_registry
for the installation sequence.
Dependency management
verum deps add codec --version 1.4.2
verum deps remove codec
verum deps update
verum deps list --tree
verum tree --duplicates --depth 3
deps add and deps remove accept --dev or --build to select the dependency
table. deps update optionally accepts one package name. These commands expose
no --require-verification flag.
Workspace publishing
verum workspace list
verum workspace add path/to/member
verum workspace remove member-name
verum workspace exec -- verum package publish --dry-run
Run these commands from the workspace root. They select Verum.toml first,
with legacy verum.toml as a fallback when the canonical file is absent. An
invalid canonical manifest is an error even if a valid legacy file also exists.
workspace add validates the member before adding its path; workspace remove
accepts a member path or package name. Both persist membership changes to the
selected workspace manifest.
workspace exec runs the supplied command sequentially in each declared member's
directory. A missing or invalid member manifest, a command that cannot start, or
a nonzero child exit makes the overall command fail. Other members are still
attempted, so a failed invocation can have completed work in some members.
Each invocation of package publish applies its own manifest and dependency
checks. It does not rewrite member dependencies or provide an atomic
multi-package release.
Implementation references
The executable dispatch is in
PackageCommands and WorkspaceCommands.
The package handler
owns archive creation and installation;
publication dependency projection,
request encoding,
and receipt checking
define the client admission boundary.