Release, Site, Configuration, and Evidence Contract

1. Purpose

Each customer delivery package binds the selected infrastructure, providers, devices, domains, capacity, policy, and release digests to exact validated values. This contract defines how every customer-specific value is instantiated and verified.

The delivery package is not a set of manually edited YAML files. Release engineering and the customer packet generator render versioned machine-readable documents from approved inputs, validate all cross-document references, produce a deterministic package digest, and collect signatures. The installer receives the final read-only package and may populate only the explicitly declared non-secret worksheet before the approval freeze.

Two package classes exist:

• certification_candidate: a non-production, lab-bound package used only by the independent Installation Certification teams to create D4 evidence. It must carry certification.status: pending, handoffReady: false, a synthetic lab customer/environment, and an expiry. It may never name a real customer, enable live value, or satisfy D5.
• customer_handoff: the production installation package. It must carry certification.status: certified, the applicable D4 scope vector and receipt, and handoffReady: true.

No customer_handoff package reaches a third party until:

• the exact release/profile/machine-contract digest holds a current D4_COLD_INSTALL_CERTIFIED receipt whose scope vector covers the proposed handoff under Installation Certification;
• all required files in Section 2 exist;
• every schema and cross-reference validates;
• no placeholder, secret literal, wildcard production value, mutable tag, expired receipt, or unresolved exception remains;
• all required Levy and customer signatures verify against independently installed trust anchors;
• the exact release/controller/CLI/site compatibility result is PASS.

2. Canonical delivery-package layout

levy-onprem-<customer>-<environment>-<release>/
  PACKAGE-INDEX.json
  PACKAGE-INDEX.sig
  README-FIRST.md

  00-trust/
    levy-root-bundle.json
    levy-root-fingerprints.txt
    customer-root-bundle.json
    signing-key-transition.json
    revocation-list.json
    revocation-list.sig

  01-release/
    release-index.json
    release-index.sig
    supported-platforms.json
    capacity-profiles.json
    compatibility-matrix.json
    component-sbom-index.json
    provenance-index.json
    vulnerability-receipt.json
    source-exclusion-receipt.json
    license-notices-index.json
    known-issues.json
    approved-release-exceptions.json
    cold-install-certification.json
    external-reference-ledger.json
    release-notes.md

  02-artifact-custody/
    delivery-mode.json
    custody-tool-receipt.json
    custody-bundle-index.json
    site-conformance-kit-receipt.json
    encrypted-media-manifest.json
    registry-import-manifest.json
    custody-ledger-template.json
    destruction-return-template.json

  03-site/
    site-packet.json
    topology.json
    network-flow-matrix.json
    dns-certificate-inventory.json
    data-classification-retention.json
    processor-egress-matrix.json
    secret-reference-ledger.json
    responsibility-raci.json
    slo-rpo-rto.json
    maintenance-launch-rollback-authority.json

  04-configuration/
    feature-manifest.json
    provider-manifest.json
    iot-protocol-command-manifest.json
    mobile-release-manifest.json
    non-secret-configuration.json
    configuration-approval.json
    configuration-approval.sigset

  05-installation-control/
    trusted-cli-distribution-receipt.json
    customer-target-policy.json
    customer-target-policy.sig
    entitlement.json
    entitlement.sig
    recovery-entitlement-template.json
    installation-request-template.json
    controller-openapi.json
    controller-openapi.sig
    cli-compatibility.json
    catalog-index.json

  06-runbooks/
    third-party-installation.md
    install.md
    upgrade.md
    rollback.md
    backup-restore.md
    disaster-recovery.md
    gateway-certification.md
    iot-failover.md
    residency-verification.md
    mobile-release.md
    support-access.md
    signing-key-compromise.md
    failed-safe-recovery.md
    uninstall-data-disposition.md
    controller-lifecycle.md
    offline-key-custody-and-rotation.md

  07-evidence/
    evidence-index-template.json
    receipt-schema-index.json
    acceptance-signature-template.json
    exception-template.json
    fixture-disposition-policy.json
    prohibited-content-policy.json

  08-training/
    installer-qualification-requirements.md
    release-specific-delta.md
    lab-rehearsal-receipt.json

  09-signatures/
    package-approvals.json
    package-approvals.sigset

PACKAGE-INDEX.json lists every file by relative path, media type, byte length, SHA-256 digest, confidentiality classification, owner, schema/document version, and required installer visibility. Any missing, extra, altered, or case-variant path fails package validation.

2.1 README-FIRST.md required content

The first page is generated, customer/release bound, and contains only:

1. package class, customer, environment, release, package ID/version/digest, certification state/scope vector, and handoffReady; a certification candidate says pending with no D4 ID, while a customer handoff names the D4 ID;
2. the authoritative out-of-band trust-fingerprint retrieval method and customer security owner; any fingerprint repeated inside this package is explicitly advisory;
3. the exact supported installer workstation/levyctl digest, Levy distribution receipt, and the external customer Phase −1 provisioning-receipt requirement; the package receipt alone never proves the workstation binary was trusted;
4. the exact local command levyctl package verify --package <package-directory> --trust <customer-installed-trust-directory> --delivery-receipt <d5-receipt> and expected PASS/exit 0, executed by that pre-provisioned trusted binary; a certification candidate omits --delivery-receipt and can return only candidate-valid, never handoff-ready;
5. the Installation Guide path/version/digest and instruction not to begin Phase 0 until package validation passes;
6. named stop/escalation routes, installation window, evidence repository, and authority record;
7. explicit prohibition on repository, Kubernetes, registry, database, Secret, node, runtime, raw-log/event, image, or undocumented access;
8. statement that missing/conflicting material is FAIL_PREREQUISITE or FAIL_RELEASE, never an invitation to infer a value.

It also states the P1 residual-risk boundary: P1 protects source distribution and ordinary installer access but cannot guarantee that a sufficiently privileged customer infrastructure owner cannot inspect runtime memory, interfaces, or behavior. It contains no architecture tutorial, secret, raw endpoint credential, workaround, mutable download URL, or instruction to contact a developer informally.

3. Common document envelope

Every JSON document has this required envelope:

{
  "schemaVersion": "1.0.0",
  "documentType": "levy.onprem.<type>",
  "documentId": "<immutable-id>",
  "customerId": "<customer-id-or-null-for-global-release-doc>",
  "environmentId": "<environment-id-or-null-for-global-release-doc>",
  "releaseId": "<release-id-or-null-when-not-yet-bound>",
  "createdAt": "<UTC-RFC3339>",
  "createdBy": { "subject": "<issuer-subject>", "role": "<issuer-role>" },
  "expiresAt": "<UTC-RFC3339-or-null>",
  "payload": {},
  "payloadDigest": "sha256:<hex>",
  "envelopeDigest": "sha256:<hex>",
  "signatures": []
}

Rules:

• payloadDigest is the SHA-256 digest of the RFC 8785-canonicalized payload and remains the stable cross-document content reference.
• envelopeDigest is the SHA-256 digest of the RFC 8785-canonicalized signed-envelope projection: the complete envelope with only the self-referential envelopeDigest and signatures fields removed. It therefore binds schemaVersion, documentType, IDs, customer/environment/release, creation/expiry, creator, payload, and payloadDigest.
• Every embedded or detached signature signs a canonical signature claim containing crypto profile/algorithm, key ID, signer role, signed/expiry times, target documentId/documentType, and envelopeDigest; only the signature-bytes field is removed from that claim before signing. It never signs payloadDigest alone. Trust policy derives authoritative role/organization from keyId and rejects a conflicting claimed role.
• customerId, environmentId, and releaseId are present even when null; a customer artifact may never use null for its required binding.
• Unknown envelope fields fail. Payload unknown-field behavior is defined by its schema and defaults to fail.
• expiresAt: null is allowed only for immutable release provenance/SBOM/license records and signed roots with a separate rotation/revocation policy.
• Every reference to another document includes its documentId, payloadDigest, and required documentType; ID-only references are invalid.

4. IDs, values, and signature rules

4.1 Identifier rules

IDs are immutable, case-sensitive lowercase ASCII, globally unique within the customer's evidence domain, and never recycled.

4.2 Value rules

• Money: { "currency": "EGP", "minorUnits": 1000 }; no floats.
• Time: UTC RFC 3339 timestamps; business timezone separately identified by IANA name.
• Duration: nonnegative integer seconds except human documentation.
• Percentage: integer basis points unless the schema states an integer percentage.
• Digest: sha256:<64 lowercase hex>.
• OCI reference: customer-local registry plus immutable digest; tags may be display metadata but never deployment authority.
• Secret: opaque reference ID only. Strings matching token/key/password/JWT/private-key patterns fail prohibited-content scanning.
• Host: exact FQDN or IP/CIDR in fields that explicitly allow it. Wildcard production hosts fail unless the schema names a narrow customer-controlled subdomain exception and customer security signs it.
• Network destination: protocol, exact host/CIDR, port/range, direction, source workload identity, purpose, data classes, owner, and approval.

4.3 Signature roles

The installer never signs as release, customer security, payment, data, or launch authority. Installer signatures attest execution/observation only.

The customer target policy pins exactly one version-1 cryptographic profile:

• modern_ed25519_age_v1: document, receipt, entitlement, revocation, binary-digest, and aggregate release-index signatures use Ed25519; offline media uses age v1 with an X25519 recipient.
• enterprise_p256_cms_v1: those signatures use ECDSA P-256 with SHA-256 and strict DER encoding; offline media uses CMS EnvelopedData with AES-256-GCM content encryption and an RSA-3072 OAEP-SHA-256 customer recipient.

For both profiles:

• keyId is sha256:<hex> of the signer's DER SubjectPublicKeyInfo, and public-key fingerprints are verified through the out-of-band channel;
• signature bytes use unpadded base64url;
• the signed message is ASCII context levy-onprem-v1:<profile>:<documentType>\n followed by the RFC 8785-canonicalized signature claim without signature bytes, preventing cross-type/profile reuse and binding signature metadata;
• each OCI/binary signature record binds media type, byte length, artifact digest, component ID, release ID, platform, and aggregate release-index digest;
• release/customer signing private keys are held in their respective approved HSM/KMS or offline signing system, never the build worker, package, controller, levyctl, or installer workstation;
• the signed media manifest binds profile, recipient fingerprint, encrypted archive digest/size, plaintext archive digest/size visible only after customer decryption, release index, media ID, and custody policy;
• the customer custodian generates the recipient key inside the residency boundary, provides only the public key through authenticated onboarding, confirms its fingerprint over a second approved channel, and records dual-custody ownership. Rotation, loss, replacement, and re-encryption follow offline-key-custody-and-rotation.md;
• each profile has profile-scoped cold-install certification. Adding a new profile is additive; changing or removing a released profile requires a schema major version, migration/rotation plan, and full cold recertification.

TLS, storage, database, backup, and secret-manager encryption remain customer-platform controls declared in the site packet; this signature profile does not replace them.

5. Package index contract

Required PACKAGE-INDEX.payload fields:

The certification scope vector contains explicit booleans for greenfieldOnline, greenfieldOffline, restore, adversarialDenial, handoff, nMinusOneUpgrade, and applicationRollback, plus predecessorReleaseId. For a first release with no predecessor, the last two may be notApplicableNoPredecessor; the first successor release must certify both before it can reach D5.

The package validator reconstructs all file digests, validates every schema/reference/signature/freshness rule, and produces a package-validation receipt. A human-edited index is invalid. A documentation erratum may change only documentationDigest and generated prose paths; it cannot change commands, arguments, machine-readable contracts, schemas, catalogs, expected values, security controls, stop conditions, or operational semantics. Any such semantic change changes machineContractDigest and requires the applicable recertification/restart.

6. Release index contract

release-index.payload is the aggregate authority for the immutable product release.

Required fields:

01-release/external-reference-ledger.json records every external vendor/platform document on which a procedure depends: vendor/document name, exact product and documentation version, authoritative URL or customer-controlled archived copy, retrieval date, content digest, accountable owner, and every runbook section that relies on it. “Use vendor documentation” without this ledger entry is invalid.

Each component entry binds:

{
  "componentId": "core-api",
  "artifactType": "oci",
  "platforms": ["linux/amd64"],
  "digest": "sha256:<hex>",
  "sizeBytes": 0,
  "runtimeUser": "10001:10001",
  "entrypointDigest": "sha256:<hex>",
  "sbomRef": { "documentId": "...", "payloadDigest": "sha256:..." },
  "provenanceRef": { "documentId": "...", "payloadDigest": "sha256:..." },
  "scanRef": { "documentId": "...", "payloadDigest": "sha256:..." },
  "sourceExclusionRef": { "documentId": "...", "payloadDigest": "sha256:..." }
}

Mutable tags, component names without digests, unsupported architecture, missing evidence references, or a scan older than the release policy block the release.

7. Supported-platform and capacity contracts

7.1 Supported platform entry

Every supported combination declares exact ranges for:

• CPU architecture and required instruction set;
• operating system/distribution/kernel/container runtime;
• Kubernetes distribution/version/CNI/CSI/ingress/certificate/admission capabilities;
• PostgreSQL/PostGIS/connection pooler/object-store versions and required features;
• registry/signature-verifier/secret-manager/identity/observability/backup integrations;
• time/DNS/PKI/TLS/cipher requirements;
• node/storage/network/failure-domain assumptions;
• security profile support and known restrictions;
• install/upgrade path from each supported prior release.

No phrase such as “recent,” “standard,” “compatible,” or “or equivalent” is accepted without a conformance test that defines equivalence.

7.2 Capacity profile

Required inputs and outputs:

Outputs include per-component CPU/memory/replicas, database connections/IOPS/storage/WAL, object capacity, network throughput, registry/evidence/backup capacity, quotas, autoscaling bounds where supported, and warning/critical thresholds. Qualification occurs at accepted peak and 2× peak with one failure domain unavailable.

7.3 Customer custody bundle

levy-custody is a separately delivered, signed, customer-only tool; it is not installer authority and is never accepted merely because a copy appears inside the application package. Its separate custody bundle contains the executable for each supported platform, detached signature, artifact digest, SBOM/provenance/source-exclusion receipts, compatibility range, command/receipt schemas, and a distribution receipt. 02-artifact-custody/custody-bundle-index.json contains only the signed digest/reference and compatibility facts for that external bundle, never its executable or credentials. Customer security verifies it using customer-controlled verification software and the authoritative out-of-band Levy root before provisioning it only to the artifact-custodian role. Its receipts bind tool digest/version, media and release digests, recipient profile/fingerprint, action, actor, case, time, and result. A tool/signature/schema/crypto-profile change requires compatibility testing; a change to encryption, decryption, import/export, or receipt semantics requires profile-scoped cold recertification.

7.4 Customer platform conformance kit

levy-sitecheck is a signed, versioned, controller-free customer tool/bundle used during discovery before D5. Customer platform/security staff run it—not the installer—to test only declared prerequisites: supported platform/version ranges, DNS/NTP/PKI, storage/backup capabilities, local registry policy, identity, evidence-store counter-signing, network flows, and capacity inputs. It emits a signed/countersigned site-conformance receipt with no raw secrets or consumer data. A PASS is necessary but not sufficient for D5; the controller repeats all install-time checks against the frozen target policy.

8. Site packet contract

site-packet.payload contains no secret values and includes:

8.1 Identity and authority

• legal customer name, immutable customer/environment IDs, country/residency boundary, business timezone;
• deployment/protection profile, release/channel, greenfield/migration classification;
• named primary/backup people for every Installation Guide role, organization, contact route, authority scope;
• change record, installation windows, blackout windows, maintenance policy;
• launch, rollback, live-value, device-wave, privacy/residency, data, and exception authorities.

8.2 Infrastructure

• physical/virtual/site topology and failure domains;
• cluster/distribution/version, API identity, node pools, labels/taints, resources, runtime, CNI, CSI, ingress, admission, audit;
• local registry repositories/retention/immutability/signature policy;
• database/pooler/object store/backup/restore endpoints and non-secret properties;
• evidence repository and counter-signing endpoint;
• secret manager and workload identity mechanism;
• monitoring/logging/tracing/on-call endpoints;
• capacity-profile input and resulting accepted envelope.

8.3 Network, DNS, and PKI

• exact ingress, internal, data, device, management, backup, evidence, and optional-support zones;
• complete directional flow matrix with data classes and owner;
• exact API/operator/IoT/object/auth/webhook/support/DNS/NTP/PKI hostnames/IPs/ports;
• certificate issuer, SAN, key type, renewal owner/route, expiry alert, trust stores;
• default-deny policy and customer-owned capture/flow-metadata method;
• every approved external processor/destination and residency/legal approval.

8.4 Data and operations

• data classification, processor, location, encryption, retention, deletion, legal hold, export, backup, and evidence policy;
• RACI, SLO, RPO/RTO, incident severity/escalation, support/access rules;
• customer operating hours, locale/RTL, currency/tax/receipt/legal policy;
• hardware spares, power/cooling/fire/security, DR site/route where physical servers are used.

Site validation fails when a role is unnamed, an endpoint is a placeholder, HA shares an undeclared failure domain, capacity lacks inputs, egress lacks a data/owner/approval classification, or a prerequisite has no accountable owner/date.

9. Feature and provider manifests

9.1 Feature manifest

For each feature/module:

{
  "featureId": "wallet",
  "state": "required|enabled|disabled|not_licensed",
  "contractVersion": "1.0.0",
  "apiRoutes": ["route-catalog-id"],
  "databaseObjects": ["schema-manifest-object-id"],
  "jobs": ["job-catalog-id"],
  "dashboards": ["dashboard-id"],
  "alerts": ["alert-id"],
  "runbooks": ["runbook-id"],
  "goldenJourneys": ["catalog-case-id"],
  "gateways": ["gateway-capability-id"],
  "retentionPolicies": ["policy-id"]
}

An enabled feature with a missing companion artifact fails configuration. Disabled/not-licensed features must have no live route, schedule, worker, dashboard expectation, client entry point, or fallback call.

9.2 Provider manifest

Each adapter entry declares:

• provider type, adapter ID/version/digest/certification receipt;
• supported capabilities and intentionally unsupported operations;
• local/sandbox/live endpoints by exact host/port/path class;
• secret-reference IDs and customer owner;
• webhook/callback URLs, signature method, replay/clock policy;
• idempotency, timeout/retry/rate/circuit-breaker behavior;
• sandbox fixtures and approved live-value limits;
• normalized error mapping, health/readiness, metrics/alerts/runbook;
• settlement/delivery/status lookup and reconciliation policy.

No provider entry may select Stripe/Twilio merely as an inherited default. A customer chooses and certifies its local adapters explicitly.

10. IoT, device, and mobile manifests

10.1 IoT protocol/command manifest

Required per protocol/device family:

• adapter/version/digest, device model/firmware/SIM/APN support range;
• authentication/credential owner and rotation;
• endpoint/DNS/IP/certificate identity and return route;
• telemetry frame types, units, timestamps, GPS precision, dedupe/order/replay;
• connection ownership, lease/fencing, failover, spool/backpressure limits;
• command name, prerequisites, safe state, acknowledgment semantics, TTL, retry, supersession, duplicate policy, audit, physical-supervision rule;
• canary inventory/cohorts, observation thresholds, rollback wave;
• real-device and simulator certification receipt.

10.2 Mobile release manifest

Required per rider/operator platform:

• application ID/bundle ID, version/build, binary digest, signing certificate/team fingerprint;
• distribution channel/store/private MDM and owner;
• exact API/operator/map/push/attestation/update destinations;
• server/controller compatibility and minimum/maximum supported client;
• feature/configuration/localization/legal-content digest;
• update policy, rollback/supersession, forced/minimum-version behavior;
• installed-base measurement and launch threshold;
• binary destination/source-map/key/fallback scan receipt;
• release approval and store/private-distribution receipt.

A binary with an undeclared endpoint, Levy Cloud/Supabase/Expo fallback, live provider key default, or unmatched configuration digest fails the package.

11. Non-secret configuration contract

The configuration is a strict schema whose complete canonical payload is signed. Required sections:

• deployment: customer/environment/release/profile/protection/region/timezone/locale/currency;
• features: feature-manifest reference and enabled module IDs;
• domains: API/operator/IoT/object/auth/webhook/support hosts;
• data: database/object/retention/partition/backup/evidence references;
• identity: operator issuer/audience/claims/MFA and rider OTP/token policies;
• payments, messaging, maps, push, attestation, supportAi: adapter refs and non-secret policy;
• iot: protocol/command/cohort refs and telemetry policy;
• pricingAndOperations: signed price/fees/pause/zone/hours/tax/receipt/legal refs;
• jobs: signed job catalog and per-job bounded configuration;
• observability: dashboard/alert/on-call/retention refs;
• security: secret refs, network/egress, admission, audit, access, redaction;
• licensing: entitlement ref and local capacity visibility policy;
• acceptance: catalog/cohort/live-value/evidence policy refs.

Rules:

• every property is required or explicitly null/disabled according to schema;
• no schema default can silently enable a production provider, route, module, job, egress destination, cloud endpoint, test bypass, or retention policy;
• unknown fields fail;
• secret-like values fail prohibited-content scanning even when placed in an otherwise free-text field;
• cross-field validation ensures modules, gateways, jobs, dashboards, runbooks, retention, mobile features, and entitlement agree;
• currency/minor-unit/pause/pricing/tax behavior is explicit and covered by golden tests;
• a changed byte after approval invalidates every signature.

12. Secret-reference ledger

Each entry contains:

The ledger contains no value, ciphertext, private key, token, password, OTP, provider credential, database URI with credentials, or export mechanism. levyctl can validate reference presence/expiry/consumer binding only through the controller's bounded service.

13. Customer target policy

The customer-owned policy is installed before the installer API is enabled. Required payload:

• customer/environment/cluster/install-controller identity;
• allowed namespace(s), resource profile/quotas, service accounts, storage/ingress classes;
• allowed local registry repositories and complete release/component/chart/policy/catalog digests;
• allowed domains, endpoints, network destinations, processors, evidence/backup locations;
• database/object/secret/identity integration references;
• protection/deployment profile, entitlement and revocation refs;
• controller/CLI/API/schema compatibility;
• allowed installation/upgrade/rollback/current/N-1 paths;
• change windows, rollout cohorts, test catalogs, failed-safe ceilings;
• admission/security-context/mount/command/entrypoint restrictions;
• installer OIDC issuer/audience/scopes/rates/session policy.

The controller cannot accept an installer-supplied namespace, registry, image, command, mount, service account, endpoint, URL, configuration field, or catalog outside this policy. The installer can retrieve only the policy digest and typed conformance result.

14. Entitlement and revocation contracts

14.1 Entitlement

Required fields:

• entitlement ID/type (production, recovery_nonproduction, emergency_extension);
• customer/environment and first-install binding inputs (cluster UID, installation receipt or approved attested identity);
• allowed release channel/range and module IDs;
• capacity bands for registered/active vehicles, concurrent rides, sites, and optional modules;
• issued/starts/expires/grace/support dates;
• safety-preserving behavior before/during/after grace;
• local capacity/mismatch/duplicate-environment evidence requirements;
• replacement/DR/recovery rules;
• signing key/revocation-list version.

Expiry or mismatch can block new starts/configuration after policy/grace but cannot block ride end/lock, pending payment/refund/webhook/reconciliation, telemetry preservation, backup/restore, customer export, or emergency recovery.

14.2 Revocation list

Required fields:

• monotonic sequence and issuedAt/nextUpdateAt;
• revoked key IDs, trust roots, release/component digests, entitlements, controller/CLI digests;
• effective time, reason code, severity, affected ranges;
• required safe behavior and recovery/runbook reference;
• replacement key/digest/entitlement where available;
• prior-list digest to form an append-only chain.

A lower/equal unexpected sequence, broken chain, stale nextUpdateAt, revoked active artifact, or signature failure blocks new install/upgrade/launch and invokes the release-defined safe response without disabling active-ride safety.

Levy release security issues a new list at least every 30 calendar days and after any revocation event. levyctl and the controller warn customer security beginning 14 days before nextUpdateAt; the customer artifact custodian retrieves and imports the update through the approved online or offline channel. A stale list blocks new install, upgrade, launch, and new entitlement activation, but never ride end/lock, safety recovery, evidence preservation, backup/restore, or already-required financial reconciliation.

15. Installation and upgrade request contract

The final request contains:

• request ID/type (install, upgrade, rollback), customer/environment/case;
• release/current/target/config/site/target-policy/entitlement/revocation/catalog digests;
• profile, namespace and infrastructure refs re-derived from target policy;
• enabled components/modules/jobs/gateways/mobile cohorts;
• database baseline/predecessor/migration sequence/recovery classes;
• planned resource/network/storage/provider/device changes;
• change window, failed-safe policy, rollback authority, evidence repository;
• complete customer and Levy approvals over the canonical payload;
• nonce, issued/expiry, idempotency key.

The schema contains no arbitrary command, args, env, image, manifest, patch, url, path, sql, script, or extension map. The controller generates the CR from verified data and makes its spec immutable. Upgrade and rollback use new request IDs; they do not mutate the accepted installation request.

16. Approval and exception contracts

16.1 Approval

An approval includes:

• approval ID, role/subject/organization, authority source;
• exact document/request envelope digest and purpose;
• customer/environment/release/case binding;
• conditions, allowed time window, maximum live value/cohort when applicable;
• issued/expiry/revoked timestamps;
• signature/key ID and audit correlation.

There is no wildcard, “latest,” “all future versions,” unbounded environment, or approval-by-email-text field. A changed payload or expired/revoked signer invalidates approval.

16.2 Exception

An exception includes:

• exact failing check/requirement and observed receipt;
• affected customer/environment/release/component;
• bounded deviation, rationale, risk owner, compensating control;
• permitted stage/actions and explicitly prohibited expansion;
• issue/remediation owner/date, expiry, review cadence;
• required signers by domain and linked evidence.

Exceptions cannot waive signature/digest verification, source-delivery restriction, installer Kubernetes denial, Secret/registry/image denial, tenant isolation, active-ride end/lock, money idempotency/reconciliation, successful restore, or signed residency/processor approval. Expired exceptions become hard failures.

17. Evidence receipt contract

Every controller/CLI/customer-tool receipt contains:

Receipts may include opaque application/provider/device operation IDs and aggregate numeric results. They must not include consumer PII, raw GPS, OTPs, tokens, payment instruments, identity documents, secret values, SQL, source, image layers, raw logs/events/pcaps, stack traces, or arbitrary provider/library errors.

Receipt result classes and CLI exits are those in Engineering and Release Reference Section 8.4. A receipt without a verifiable customer evidence-repository counter-signature is provisional and cannot close a phase.

18. Evidence index and acceptance contract

The evidence index is append-only and contains:

• package/site/config/request/entitlement/revocation/trust refs;
• package class, crypto profile, D4 certification scope vector, machine-contract digest, and documentation digest;
• Phase 0–19 and I0–I11 crosswalk;
• required/observed receipt IDs/digests/status;
• exceptions and expiration state;
• approver matrix and signature state;
• as-built component/schema/mobile/gateway/policy digests;
• fixture inventory/disposition/report-exclusion result;
• installer identity/media/workspace/cache revocation/closure result;
• final customer/Levy/launch acceptance signatures.

The evidence repository enforces write-once receipt versions, immutable digest addressing, retention/legal hold, in-boundary storage, access audit, backup/restore, and counter-signing. Corrections append a superseding receipt referencing the original; they never overwrite evidence.

Final acceptance verification fails on a missing phase, non-PASS unapproved result, expired exception/approval, digest mismatch, stale/revoked artifact, absent required signer, unclassified fixture, unexplained financial variance, undeclared egress, incomplete restore, or remaining installer access/cache/media.

19. Installation-fixture disposition contract

The fixture marker propagates to every synthetic/test-created:

• rider/operator/test identity and session;
• ride/reservation/price/fare/metering record;
• wallet/payment/authorization/capture/refund/settlement/webhook record;
• message/OTP/delivery record;
• vehicle/device command/telemetry/GPS state;
• photo/object/document/agreement;
• job/outbox/inbox/audit/reconciliation record.

The signed disposition policy classifies each domain as:

• DELETE_REFERENTIALLY_SAFE;
• QUARANTINE_EXCLUDED;
• RETAIN_AUDIT_ONLY;
• RETAIN_REAL_VALUE_RECONCILED;
• EXPIRE_WITH_BACKUP_OBJECT_POLICY.

It names owner, tool/catalog, retention/expiry, report/analytics/payout/tax treatment, backup effect, and verification query/catalog. Direct SQL deletion is prohibited. The first normal production report/settlement must prove synthetic fixtures are excluded while real live capture/refund/fees remain separately identified and reconciled.

20. Runbook contract

Every runbook includes:

• purpose/scope and exact supported release/profile;
• owner/on-call/escalation and required authority;
• triggers, prerequisites, safe-state checks, commands/API verbs, expected typed results;
• stop conditions and prohibited shortcuts;
• data/security/residency considerations;
• rollback/recovery/disable steps;
• verification receipts and evidence path;
• known failure modes and maximum failed-safe hold;
• compatibility/last-tested/certification metadata.

Runbooks use only an independently provisioned released levyctl, controller verbs, customer-owned infrastructure tools explicitly assigned to customer roles, and documented dashboards. They cite exact entries from the external-reference ledger for any customer-platform/vendor instruction. They do not instruct an installer to use Kubernetes, registry, shell, node, database, Secret, raw log/event, or provider-admin access.

21. Package generation and validation workflow

1. Release engineering selects one D3 release and generates immutable release/global artifacts. Before D4 it may generate only a synthetic certification_candidate; after D4 scope validation it may generate a customer_handoff candidate for D5.
2. Customer discovery imports approved site/provider/device/mobile/capacity/residency decisions.
3. Generator validates that every selected feature has its complete companion set and certification receipt.
4. Customer tools render the target policy, site packet, secret-reference ledger, configuration, responsibility, and authority documents.
5. Levy/customer owners review non-secret rendered content and resolve every failure/exception.
6. The generator canonicalizes/hashes documents; owners sign exact digests.
7. Customer security retrieves the authoritative fingerprint from a signed onboarding/commercial artifact delivered outside this package, installs trust anchors out of band, independently verifies/provisions levyctl, levy-custody, and levy-sitecheck, and verifies signatures/revocation/freshness. A mismatch is FAIL_SECURITY.
8. Package builder creates PACKAGE-INDEX, runs schema/cross-reference/prohibited-content/placeholder/digest/signature/compatibility/freshness validation, and signs the package.
9. A clean validation environment repeats verification using only the distributed trust roots/fingerprints and package.
10. A certification team may receive an expiring lab-only candidate before D4. A production installer receives a read-only customer_handoff package plus access to the in-boundary evidence repository/controller only after D5 approval.

Package generation is reproducible: identical approved payload inputs and release artifacts produce identical payload and machine/documentation contract digests. Full envelope/file digests may differ only where schemas explicitly permit creation/signature timestamps; those timestamps and resulting envelope digests are themselves signed and recorded, never ignored during validation.

22. Placeholder and prohibited-content validation

The package is rejected if any non-template text or machine-readable value contains:

• <...>, TODO, TBD, CHANGEME, example.com, localhost, latest, dummy IDs, template sentinel values, or empty required strings;
• wildcard production host/port/network values not expressly modeled and signed;
• secret-like material, private keys, bearer/JWT/provider/database credentials, .env content;
• raw consumer/customer PII or GPS;
• mutable image/chart/binary references;
• hosted fallback destination not listed in the signed egress/processor matrices;
• an expired, revoked, mismatched, unsigned, or unknown-schema document;
• a file not declared in PACKAGE-INDEX or a declared file not present.

The only placeholder exemption is a document with documentType: levy.onprem.template.<type> stored at a schema-declared template path. Its schema enumerates the exact placeholder vocabulary and allowed field locations; undeclared tokens still fail. A template is never accepted by the controller as site policy, configuration, approval, entitlement, installation request, evidence, or another live document. The validator uses no free-text exemption.

23. Definition of a handoff-ready package

A customer_handoff release/customer package is handoff-ready only when:

1. Its complete canonical tree in Section 2 exists and validates.
2. It binds one customer, environment, release, controller API, CLI range, site, configuration, target policy, entitlement, and revocation state.
3. Every product component, chart/policy/catalog/schema/runbook/mobile/gateway artifact is immutable and digest-addressed.
4. Required source-exclusion, SBOM, provenance, vulnerability, license, compatibility, capacity, and profile-scoped cold-install receipts pass and remain fresh; the D4 scope vector covers every scope required for this release and predecessor path.
5. Infrastructure, failure domains, capacity, DNS, PKI, network, data, processor, retention, secrets, providers, devices, mobile, operations, and authority fields are complete.
6. No secret value, source, source map, prohibited endpoint, wildcard, mutable tag, unresolved placeholder, or consumer data is present.
7. All cross-document references and all Levy/customer signatures verify from out-of-band trust roots and the newest revocation list.
8. Every exception is allowed, exact, signed, unexpired, and does not waive a non-waivable invariant.
9. The installer has the exact compatible Installation Guide, training delta, an independently provisioned and verified levyctl, controller access policy, and in-boundary evidence destination. The package contains only the CLI distribution/verification receipt as authority.
10. The package validator emits an external D5_SITE_READY receipt over the final immutable package/envelope digest and customer/Levy release authorities countersign that receipt. The package is not rewritten after D5; the countersigned receipt travels with the delivery record and is verified before access is granted.

Only then can Installation Guide be handed to a third party “as is” for that exact customer and release. Readiness belongs to that exact release, crypto profile, certification scope, site, and package—not to Engineering and Release Reference as a document. A blank template, certification candidate, or global release alone is never an installation package.