Skip to content

Latest commit

 

History

History
107 lines (87 loc) · 6.03 KB

file-formats.md

File metadata and controls

107 lines (87 loc) · 6.03 KB

Persisted file formats

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

Download lock

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.

Environment cache and deployment dump

Both files are trusted PHP, beginning with:

<?php
// @generated by sympress/runtime env-cache:v1

They 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.

Immutable runtime payload

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.

Internal recovery records

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.

Verification

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.