Runtime 1.x reads the supported 0.2 formats below. New writers retain format 1;
the download lock gains an additive format field. Format versions are integers,
independent of the package release version. Unknown, missing or incorrectly typed
discriminators fail closed, except for the documented version-only download lock.
There is no supported format 0.
| Artifact | Discriminator | Upgrade behavior |
|---|---|---|
sympress-runtime.lock |
format: 1, with version: 1 retained |
Version-only 0.2 locks are read unchanged; the next changed lock write adds format |
.env.cached.php |
env-cache:v1 header and returned format: 1 |
Read compatible data; invalidate stale native source signatures |
.env.dump.php |
Same header and returned format: 1 |
Read compatible data unchanged; rebuild explicitly for a new environment |
var/runtime/<fingerprint>/manifest.json |
format: 1 |
Preserve old payloads; setup publishes a new immutable fingerprint |
The JSON object contains format, the compatibility alias version, and
downloads. Each download key is a lowercase SHA-256 digest of its original URL
or logical artifact identity; each value is the lowercase SHA-256 content digest.
Raw URLs, credentials and tokens are not serialized. Keys are sorted when writing.
For the WP-CLI executable, the logical key hashes
sympress-runtime:artifact:wp-cli.phar; its URL and checksum response have their
own entries. See Downloads for checksum and update behavior.
The 0.2 object {"version":1,"downloads":{}} is still supported. Reading does
not rewrite it. A subsequent write that changes pins emits both format: 1 and
version: 1, preserving the 0.2 reader contract. Existing pins are retained unless
explicitly updated. format: 1 without the alias is also readable by 1.x.
If both discriminators exist they must both equal the integer 1. An explicit
unknown format cannot fall back to version: 1. Even --update-lock cannot
replace an unsupported lock; use a compatible Runtime version to inspect it.
The lock is published atomically with private permissions. Its sibling
.sympress-runtime.lock.guard is a transient synchronization file, not a
deployment format or committed artifact.
Both files are trusted PHP, beginning with:
<?php
// @generated by sympress/runtime env-cache:v1They return an array with integer format: 1, string profile and environment,
values, loaded, types and constants arrays. values maps variable names to
[raw string, typed scalar or null]. loaded and constants are name lists;
types maps names to filter names. The optional compatibility boolean defaults
to true for older supported data. A mismatch against the configured mode fails;
flush the runtime cache or rebuild the deployment dump after changing that mode.
Native runtime caches record sources: absolute attempted paths mapped to
[size, mtime], or null for a missing file. Missing or stale source records
invalidate an otherwise supported runtime cache. Dumps write sources: null and
are not invalidated by changed source files. Format validation happens before
source checks, so an unknown future format cannot be silently discarded and
overwritten as a cache miss. Actual process values still take precedence.
Writers replace only the canonical generated version-1 prefix, including the
first returned format field. They preserve unknown headers, versions and
noncanonical user files without executing existing PHP to check ownership.
Loading a supported file executes trusted PHP; the marker is not a sandbox or
cryptographic authenticity check. Keep both artifacts private and out of version
control. _FILE references remain references rather than copied secret bytes.
See Environment for permissions and precedence.
The JSON manifest contains integer format: 1, a SHA-256 fingerprint matching
the directory name, and files, a relative-path to SHA-256 map. The manifest
itself is excluded from that map. The payload includes bootstrap.php, scoped
environment/parser sources and license notices. Its bootstrap marker remains
bootstrap:v1. See Deployment for the required artifacts.
Setup verifies exact bytes before reusing its expected immutable payload. A modified or future-format manifest at that location fails without replacement. Existing 0.2 payloads remain available for their old configuration references; they do not require in-place migration. A newly generated configuration references the new payload only after publication. Keep each rollback configuration with its matching payload.
Pruning recognizes only supported, fully verified ownership manifests. It retains unknown future formats, unrecognized files and active payloads, even with zero inactive retention. It does not convert unknown ownership into permission to delete a directory. The format marker alone does not prove that a payload is safe.
Package-layout inventories and pending recovery journals, backup ownership receipts, setup baselines and kernel build records are internal operational data. They are not extension APIs. Retain pending journals and owned backups until recovery completes; use Runtime setup, drift and prune commands to manage them. Do not edit an internal discriminator to force acceptance by an older release. Their integrity and version checks are implementation safeguards rather than a general-purpose import/export interface.
DownloadLockTest exercises the version-only migration, unchanged prior pins and
unsupported discriminator rejection even with explicit updates.
PersistedEnvironmentFormatTest loads prior format-1 caches/dumps in separate PHP
processes, checks current writer markers, and rejects future versions before
hydration, stale-source fallback or replacement. RuntimeBundleTest verifies
immutable manifest rejection; PrunerTest verifies supported old payload retention
and preservation of unknown future manifests.