RPX application packages

RPX separates application dependency state from package authoring and from the canonical published archive manifest. The three files have different jobs:

package.rbe.json is never package archive metadata. package.rbe.toml is authoring input and is not copied into a published archive. rpx compile.package generates one canonical package.rbe.yaml from the checked authoring model and embeds .rbe/package-index.json beside it.

Application manifest

Example:

{
  "format": 1,
  "name": "my-rbe-app",
  "version": "1.0.0",
  "packages": {
    "advancenet": "^1.4.0",
    "rbe-tools": {
      "version": "^1.0.0"
    }
  },
  "scripts": {
    "dev": "backend -debug",
    "check": "backend check --settings settings.json"
  }
}

A package declared directly in packages is a root package and may become visible to the application's REL package import surface. Dependencies declared by that package remain root-scoped private dependencies. Installing root alpha and root beta may therefore resolve different versions of the same private package without exposing that private package as an application root.

Custom source entries are parsed but fresh installation currently fails closed. RPX will not install an arbitrary source until that source can be pinned by the application contract with the hashes needed to preserve the same verified-install guarantees as registry artifacts.

Registry configuration

RPX reads the frozen Kastrick registry API. If no registry override is supplied, RBE uses:

https://kastrick-backend.onrender.com

Override precedence is:

1. --registry <url> for the current invocation;
2. RPX_REGISTRY_URL;
3. legacy RBE_RPX_REGISTRY_URL;
4. the built-in Kastrick Render registry above.

For example:

RPX_REGISTRY_URL=https://registry.example

or for one invocation:

rpx --registry https://registry.example index update
rpx install --registry https://registry.example

The same default/override chain is shared by public registry reads, installs, publisher/device-login flows, package status, and publication commands.

Production registry URLs must use HTTPS. Plain HTTP is accepted only for loopback development hosts.

The frozen public read endpoint is GET /api/rpx/index:

• ?index-list returns the revisioned package/version snapshot used for semver selection.
• ?package=<name>&version=<exact-version> returns the exact published release metadata and artifact pins.

RPX validates the registry authority, schema, revision, package/version identity, publication/yank state, HTTPS artifact URL, artifact SHA-256, manifest SHA-256, and artifact size before an artifact is admitted.

Local index

Refresh the application-local index with:

rpx index update

RPX stores the normalized snapshot at:

.cache/library/index.rbe.json

The local index is a resolution cache, not package authority. Exact artifact identity still comes from a validated exact release response or an existing lock.

Install

Install the current application with:

rpx install

or point RPX at a child/application path:

rpx install ./path/to/project

For a fresh or stale-lock install RPX performs this sequence:

package.rbe.json
        ↓
frozen registry index revision
        ↓
exact semver selection
        ↓
exact package metadata
        ↓
hardened staged download
        ↓
SHA-256 + size verification
        ↓
package.rbe.yaml + .rbe/package-index.json verification
        ↓
content-addressed cache promotion
        ↓
root/private dependency graph
        ↓
.cache/package.rbe.lock.json

All exact package responses in one fresh install must match the same index revision. If the registry revision changes during resolution, RPX fails and asks for a retry rather than mixing releases selected from different snapshots.

Artifact download and promotion reuse RBE's hardened install executor: bounded/resumable downloads, streaming SHA verification, expected-size enforcement, symlink/path checks, disk-budget checks, and no-clobber content-addressed promotion.

The lock is written only after the complete requested root/private graph succeeds.

Generated lock

RPX stores application lock state at:

.cache/package.rbe.lock.json

The lock contains:

• the canonical package.rbe.json fingerprint;
• the registry index revision used for a fresh resolution;
• exact root package versions and artifact pins;
• exact root-scoped private dependency graphs;
• artifact URL, package SHA-256, manifest SHA-256, size, and dependency requirements.

Conceptually:

{
  "format": 1,
  "manifest_sha256": "...",
  "index_revision": "rev-42",
  "packages": {
    "alpha": {
      "requested": "^1",
      "version": "1.5.0",
      "artifact_url": "https://...",
      "artifact_sha256": "...",
      "manifest_sha256": "...",
      "artifact_size": 12345,
      "dependencies": {
        "shared": "^1"
      }
    }
  },
  "private": {
    "alpha": {
      "shared": {
        "requested": "^1",
        "version": "1.9.0",
        "artifact_url": "https://...",
        "artifact_sha256": "...",
        "manifest_sha256": "...",
        "artifact_size": 6789,
        "dependencies": {}
      }
    }
  }
}

The important part is the private[root][package] scope. It preserves RBE's rule that a transitive package belongs to the root that required it and does not automatically become directly importable by the application.

Cache reuse and offline rehydration

Verified artifacts live at:

.cache/library/<artifact-sha256>/artifact.rbe

When package.rbe.json still matches the lock, rpx install does not need to perform registry resolution. Each root and private package is revalidated against its exact locked version, URL, SHA-256, size, canonical archive manifest, and embedded package index. Existing matching cache bytes are rehashed and reused. Missing bytes are rehydrated from the exact locked artifact URL.

This means repeat installs are lock-driven rather than "latest"-driven, while corrupted cache data is rejected instead of being trusted because a path exists.

Scripts

Application scripts are declared in package.rbe.json:

{
  "scripts": {
    "dev": "backend -debug",
    "check": "rpx install && backend check --settings settings.json"
  }
}

Run one with:

rpx run dev

Scripts execute with the application root as their working directory. RPX prepends the directory containing the current RPX executable to the child PATH, so a project-local installation can invoke rpx again from a script without requiring a global RPX install.

RPX never runs application scripts implicitly during install or package compilation.