Engineering and Release Reference

1. Purpose and document hierarchy

This reference defines the released product components, stable repository ownership boundaries, external contracts, installation control plane, packaging rules, and evidence used to qualify Levy Core On-Prem.

The document hierarchy is:

1. Platform Architecture defines product scope, architecture, invariants, and program gates.
2. This plan defines the product implementation and release-engineering contract.
3. Release Package Contract defines the machine-readable release, customer, configuration, approval, entitlement, and evidence packages.
4. Installation Guide defines the installer-facing execution procedure.
5. Installation Certification proves that a release and its instructions can be executed cold by an independent installer.
6. Documentation Overview is the readiness ledger and end-to-end traceability index.

If documents conflict, the more specific normative contract controls, provided it does not weaken a safety, financial, residency, security, or installer-access invariant from the architecture and installation references. A conflict that would weaken one of those invariants blocks the release until all documents are corrected and re-signed.

2. Frozen implementation assumptions

These assumptions allow implementation to proceed without reopening architecture during ordinary development:

• The first GA profile is native_local, production_ha, protection profile P1.
• The runtime has no hosted Supabase, Vercel, Stripe, Twilio, Expo OTA, Levy Cloud, Sentry SaaS, analytics, CRM, or mandatory OpenAI dependency.
• Customer-support AI is an optional isolated bridge and is disabled by default.
• Kubernetes is the production orchestrator. Compose is permitted only for development and explicitly labeled P0 pilots.
• PostgreSQL with PostGIS is the system of record. PostgreSQL outbox/inbox and lease-backed jobs are the version-1 event/job transport.
• Object storage, operator OIDC, rider OTP, payment, messaging, maps, mobile distribution, and IoT endpoints are customer-owned or customer-approved local services behind Levy contracts.
• The customer operates the cluster, registry, database, object storage, network, PKI, secret manager, backup system, monitoring, and first-line operations.
• The third-party installer receives no Kubernetes, registry, database, object-store, backup, Secret, node, runtime, or image access.
• The installer uses a signed levyctl client against a local installation-controller API with the exact bounded model in Installation Guide Section 33.
• A customer with root, registry, hypervisor, or hardware authority can inspect executable bytes in P1. Contracts, custody, audit, minimal images, and absence of original source are the protection; impossible inspection is not promised.
• All customer data, GPS, logs, metrics, traces, objects, backups, evidence, and installer workspaces remain inside the declared boundary unless a separately approved processor/flow is listed in the signed site packet.
• Greenfield installation is the baseline. Existing-customer migration is a separate signed addendum.
• Mobile applications use Levy APIs only. No production client performs direct database/Supabase access or contains a fallback to Levy/cloud infrastructure.
• Money and safety invariants in the architecture and installation references take precedence over availability: active rides must be endable and lockable; payment/wallet operations are idempotent and reconcilable; licensing or optional dependency failure cannot strand a ride.

Customer-specific provider, device, localization, capacity, retention, RPO/RTO, and infrastructure versions are required inputs to a release/site packet; they are not guessed in source code.

3. Released configuration

4. Required repository structure and ownership

The implementation may evolve internally, but the following owned surfaces must exist and remain stable for release automation:

src/config/deployment-profiles/
  schema/
  native-local/
  validation/

src/lib/platform/
  auth/
  database/
  storage/
  jobs/
  events/
  secrets/
  observability/

src/lib/gateways/
  payments/
  messaging/
  maps/
  support-ai/
  contracts/
  testkits/

src/lib/onprem/
  entitlement/
  residency/
  release-metadata/
  fixture-classification/

src/services/
  core-api/
  core-worker/
  operator-web/
  iot-gateway/
  adapters/

deploy/onprem/
  release-index-schema/
  installation-controller/
  installer-api-contract/
  installation-request-crd/
  signed-bootstrap/
  admission-policies/
  network-policies/
  helm/
  compose/
  database/
  observability/
  backup-restore/
  conformance/
  support-bundle/

tools/levyctl/
  cmd/
  protocol/
  receipt/
  signing/
  redaction/

tools/levy-custody/
  release/
  registry/
  offline-media/
  receipts/

tools/levy-sitecheck/
  cmd/
  checks/
  receipt/
  signing/

schemas/onprem/
  release/
  site/
  config/
  approval/
  entitlement/
  installation/
  evidence/
  revocation/
  fixture/

docs/runbooks/onprem/
  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
  uninstall-data-disposition.md
  signing-key-compromise.md
  failed-safe-recovery.md
  controller-lifecycle.md
  offline-key-custody-and-rotation.md

Each top-level surface has a CODEOWNERS entry, threat-model owner, test owner, and release approver. Changes to schemas, controller verbs, state transitions, safety/financial behavior, compatibility ranges, signing, redaction, or evidence formats require a compatibility review and release-note entry.

5. Product component contract

5.1 Core API

The core API is the only production application entry point used by rider, operator, and approved adapter clients. It must:

• own authentication context translation, subaccount isolation, authorization, validation, idempotency, and audit;
• expose versioned rider/operator/device-support endpoints with an explicit compatibility window;
• own a signature-authenticated, replay-protected provider-webhook inbox surface for configured local payment/messaging adapters; adapters normalize and enqueue callbacks but never expose provider administration to the installer;
• contain no hosted-service fallback or direct dependency on Supabase client semantics;
• enforce all ride, pricing, wallet, payment, refund, reservation, agreement, photo, zone, and vehicle invariants server-side;
• use platform/gateway interfaces rather than provider SDKs outside adapter modules;
• emit transactional outbox records in the same database transaction as business state;
• reject unknown configuration/module combinations at startup and readiness;
• remain able to end/lock active rides and record pending financial intents during optional-provider outages;
• expose only /live, /ready, /version, and authenticated application APIs; diagnostic detail belongs in local telemetry, not public responses.

Acceptance requires contract tests for every supported client version, tenant-isolation tests, idempotency/replay tests, dependency-outage safety tests, and the Platform Architecture golden journeys.

5.2 Core worker

The core worker executes the signed job catalog. Every job definition includes owner, schedule/trigger, idempotency key, concurrency, timeout, retry policy, backoff, terminal state, alert, pause/resume rule, recovery command, and retention. At minimum it implements:

• outbox delivery and inbox/webhook processing;
• ride metering and completion/recovery;
• payment, wallet, refund, and settlement reconciliation;
• reservation/hold expiry;
• device telemetry normalization and stale-state evaluation;
• IoT command timeout/retry/supersession;
• photo/stuck-end recovery for enabled modules;
• retention/partition/object deletion;
• backup/restore verification triggers;
• certificate/secret/entitlement/revocation freshness checks;
• synthetic health and fixture-disposition verification.

No job is enabled merely because code exists. The signed feature/configuration manifest enables the job and its companion dashboard/alert/runbook as one unit.

5.3 Operator web and mobile clients

All clients must:

• call only the configured Levy API and approved public map/push/attestation endpoints;
• fail closed on a missing production endpoint rather than use a compiled default;
• contain no database URL/key, provider secret, server authorization rule, financial invariant, or license enforcement secret;
• ship no source maps or original source in customer-delivered artifacts;
• expose their build, API-contract, configuration, update-channel, and signing-certificate identifiers in an authenticated diagnostics screen;
• enforce server-signed minimum/maximum compatible versions;
• use customer-approved store/private distribution and update channels; hosted Expo OTA is not part of the native-local production profile;
• support the customer locale, Arabic/RTL where selected, currency minor-unit rules, timezone, legal content, and map policy from the signed configuration.

Release qualification includes binary destination scanning, fallback-string scanning, source-map scanning, certificate/update-channel verification, offline/poor-network journeys, deep-link/QR checks, and version-skew tests.

5.4 Data platform

The native-local data platform must provide:

• an idempotent empty-database baseline named and versioned independently from SaaS migration history;
• ordered expand/contract migrations with a declared application_rollback, forward_fix, or restore_required recovery class;
• Levy-owned schema manifests and a customer-object inventory that tolerates declared monitoring/backup objects without allowing shadowing or search_path drift;
• explicit tenant/subaccount scope on every customer-owned row and repository method;
• local identity subjects independent of hosted auth identifiers;
• immutable financial and audit ledgers with corrective entries rather than destructive rewrites;
• partition/retention/deletion rules for GPS, telemetry, audit, logs, jobs, messages, objects, and consumer data;
• an immutable installation_fixture_id classification propagated across every test-created domain record;
• transactional outbox/inbox, lease/fencing, idempotency, and reconciliation tables;
• least-privilege runtime, migration, reporting, monitoring, and backup database roles.

The baseline generator, migration runner, schema manifest, and recovery verifier are release artifacts. Direct manual SQL is not an installation or recovery mechanism.

5.5 Gateway adapters

Payment, messaging, operator identity, rider OTP, maps, push/attestation, and IoT integrations use versioned contracts. A concrete adapter is deliverable only when it includes:

• declared capability/version matrix;
• configuration schema and secret-reference schema;
• request/response/error normalization;
• idempotency/replay/timeout behavior;
• health and readiness semantics;
• redacted metrics/logs/audit;
• sandbox/simulator fixtures;
• certification suite and signed receipt;
• provider outage and recovery runbook;
• rate/capacity assumptions and alert thresholds.

Payment adapters additionally prove timeout-after-success, duplicate/out-of-order/missing webhooks, 3DS/local-auth flows where applicable, refund/void distinction, settlement lookup, and zero-variance ride/payment/wallet/provider reconciliation. Messaging adapters prove sender/template approval, OTP expiration/replay/rate limiting, delivery callbacks, duplicate suppression, throughput, spend controls, and provider outage behavior. IoT adapters prove connection ownership, fencing, command safety, acknowledgment, TTL, retry, supersession, telemetry replay, clock normalization, canary return, and split-brain denial.

5.6 Observability, backup, and operations

The product ships local dashboards, alerts, metrics, structured logs, traces where enabled, and audit events for:

• API availability/latency/error and auth denial;
• active rides, ride-end/lock failures, metering lag/deduplication;
• payment/wallet/refund/reconciliation/settlement variance;
• messaging/OTP delivery and abuse controls;
• IoT connections, ownership, command state, telemetry age/backpressure;
• worker schedules, leases, retries, dead letters, overdue jobs;
• database replication/storage/locks/connections and object-storage capacity/errors;
• backup age, PITR window, restore rehearsal, and recovery entitlement;
• certificates, Secrets, signing roots, revocation lists, entitlement/capacity;
• unauthorized egress, admission denial, privileged access, and installer API denial;
• installed/config/schema/mobile/gateway version skew.

Every alert contains severity, owner, customer/environment, runbook link, safe first action, and correlation ID without consumer data or secrets. Backup success is not green unless an isolated restore has passed within the configured interval.

6. Engineering work packages

Every work package produces code, tests, documentation, release artifacts, and a signed CI receipt. A package cannot be marked complete with mocked happy-path behavior alone.

WP-01 — Dependency census and profile enforcement

Build: a machine-readable dependency/route/module/job/provider matrix; deployment-profile schema; compile/startup validation; prohibited-host/fallback scanner; build-time and runtime feature composition.

Target surfaces: src/config/deployment-profiles/, build configuration, web/mobile app configuration, dependency census under docs/architecture/onprem/.

Acceptance: native-local builds fail on hosted Supabase/Vercel/Stripe/Twilio/Expo OTA/Levy-cloud/Sentry/analytics/CRM destinations, wildcard production hosts, source maps, test-auth bypasses, or an enabled module missing its jobs/dashboard/runbook.

WP-02 — Platform interfaces and native repositories

Build: auth, database, storage, jobs, events, secrets, clock/ID, and observability interfaces; native implementations; test doubles; request-scoped tenant context; replacement of direct Supabase usage in reached core routes.

Acceptance: the full core route catalog compiles and passes without importing hosted clients outside quarantined compatibility adapters; tenant isolation and authorization suites pass at repository and API layers.

WP-03 — Database baseline and lifecycle

Build: clean baseline, normalized identity/domain schema, role/grant manifests, migration/recovery ledger, expand/contract migration runner, schema manifest, backup/PITR/restore jobs, retention/deletion, fixture propagation/disposition.

Acceptance: empty install, upgrade from a frozen synthetic prior-baseline fixture (and real N-1 when a predecessor exists), failed migration recovery, schema drift, isolated restore, retention, and fixture-disposition tests pass with financial/audit invariants intact.

WP-04 — Identity and authorization

Build: local rider OTP/token service, operator OIDC/JWKS integration, service/device identity, session/revocation, MFA/role/group mapping, break-glass, account deletion/export, attestation interface, audit.

Acceptance: login/refresh/logout/revocation/lost-device/clock-skew/key-rotation tests, unauthorized-role/tenant tests, OTP abuse/replay/rate tests, and IdP/attestation outage ride-end tests pass.

WP-05 — Payment, wallet, and messaging gateways

Build: stable contracts, reference simulators, one certified first-customer payment adapter, one certified first-customer messaging adapter, capability negotiation, normalized errors, webhook inboxes, reconciliation, evidence-safe diagnostics.

Acceptance: every Platform Architecture adapter test plus three clean settlement cycles in a controlled prelaunch environment; no real credential enters code, config artifacts, logs, or evidence.

WP-06 — Core ride and operator journeys

Build: API-backed rider/operator flows for discovery, zones, pricing, reservations, agreements, unlock/start, metering, pause policy, end/lock, payment/wallet/refund, receipts, vehicle management, roles, audit, and enabled optional modules.

Acceptance: all 21 golden journeys and failure variants pass using production-like mobile/operator clients and the native-local data plane.

WP-07 — IoT/GPS control plane

Build: local device endpoints, protocol adapters, connection registry, fencing/ownership, durable commands, telemetry normalization/spooling, retention, firmware/object routing, simulators, real-device certification.

Acceptance: restart/failover/split-brain, duplicate/out-of-order telemetry, clock skew, queue TTL/retry/supersession, canary return, lock/unlock/end safety, and 2× peak load tests pass.

WP-08 — Durable jobs and reconciliation

Build: signed job catalog, lease/fencing library, schedules/triggers, idempotency framework, admin pause/resume/recovery surface, histories, alerts, and every companion job required by enabled modules.

Acceptance: forced leader loss, retry storm, duplicate trigger, timeout-after-success, poison record, backlog recovery, and reconciliation convergence tests pass without double accrual/capture/message/device command.

WP-09 — Mobile/operator release system

Build: native-local environment selection, no-fallback endpoint injection, customer branding/localization, signing/distribution, update policy, compatibility enforcement, binary metadata, private-store option, destination/source-map scan.

Acceptance: signed production candidates run all required journeys against a local lab, reject mismatched server/config/update channels, and contain no prohibited endpoint/key/source map.

WP-10 — Runtime packaging and infrastructure contract

Build: minimal signed images, internal Helm chart, P0 Compose, network/admission policies, security contexts, Pod disruption/topology rules, resource profiles, storage/ingress/TLS contracts, dashboards/alerts, backup/restore jobs.

Acceptance: source/layer/SBOM/provenance/vulnerability/license scans, ephemeral HA install, node/zone disruption, default-deny egress, capacity, restore, and image-retention/rollback tests pass.

WP-11 — Installation controller and immutable request

Build: signed bootstrap, CRD/CEL, customer-owned target policy, reconciliation state machine, API from Section 8, typed status, failed-safe/rollback behavior, upgrade support, controller audit/redaction, admission coordination.

Acceptance: deterministic install/upgrade/rollback, controller restart/replay, TOCTOU/spec mutation, wrong target/image, parallel mutation, dependency failure, timeout, and every Installation Guide Section 33 negative test pass. The installer has no Kubernetes identity.

WP-12 — levyctl

Build: signed cross-platform client, independently verifiable distribution bundle/receipt, configuration rendering/validation, API authentication, full-envelope request signing, receipt verification, progress/status, evidence repository integration, local cache encryption/deletion, stable exit/error contract, offline help. The customer verifies and provisions the CLI before installer access; no package-contained copy may establish its own trust.

Acceptance: CLI/API compatibility matrix, malformed/unknown input rejection, expired/wrong-audience auth, replay, interrupted upload/resume, cache deletion, redaction, signature verification, and unsupported-version behavior pass. The binary contains no source, credentials, server implementation, or hidden cloud dependency.

WP-13 — Supply chain, custody, trust, entitlement, and revocation

Build: reproducible release pipeline, aggregate release index, canonical full-envelope signatures, both Release Package Contract v1 crypto profiles, SBOM/provenance/scans, encrypted offline archive, separately distributed signed customer-only levy-custody import/verification bundle, customer-scoped custody/import, in-boundary recipient-key creation/rotation/loss/re-encryption workflow, trust-anchor bootstrap/rotation, 30-day monotonic revocation-list lifecycle, environment-bound entitlement, recovery entitlement, local capacity/clone evidence. levy-custody is never in the installer package and its credentials are not accepted by the controller API or levyctl.

Acceptance: online/offline import, altered archive/index/signature, revoked key/digest/entitlement, stale list/scan, cluster replacement, DR recovery, capacity overage, duplicate environment, emergency extension, and safety-preserving expiry tests pass.

WP-14 — Conformance, fixtures, evidence, and support

Build: fixed signed test catalogs, tagged fixtures across every domain, redacted typed receipts, in-boundary evidence repository, counter-signing, fixture disposition, reporting/payout exclusions, encrypted support bundle, customer-only decryption, acceptance assembly, and the signed controller-free levy-sitecheck customer platform conformance kit.

Acceptance: every Installation Guide phase produces its specified receipt; evidence prohibited-content scans pass; normal reports/payouts exclude synthetic fixtures; live-value records reconcile separately; cache/media/access closure is verifiable.

WP-15 — Customer delivery and cold-install certification

Build: generated Release Package Contract release/site packets, complete runbooks, compatibility/support matrix, installer training/exam/lab, issue/exception process, Installation Certification cold-install harness.

Acceptance: two consecutive independent cold installations for the same release/profile/machine contract pass with no undocumented assistance or unresolved severity-1/2 defect. A first release certifies greenfield online/offline, restore, adversarial denial, and handoff, and records N-1/application rollback as notApplicableNoPredecessor; its first successor must add N-1 upgrade and application-rollback scopes before D5.

7. Installation controller architecture

7.1 Trust boundaries

The controller is customer-local and is the only component allowed to translate an approved installer request into Kubernetes, registry, database-migration, backup, conformance-job, or evidence actions. It has separate least-privilege identities for:

• controller control-plane reconciliation;
• runtime image pull;
• namespace/workload application;
• database migration;
• preflight/conformance read probes;
• backup/restore verification;
• evidence signing/writing;
• support-bundle generation.

One broad service account is prohibited. Each identity is audience/namespace/action bound, rotated, audited, and referenced in the bootstrap manifest. The controller cannot read provider secret values for return to its API; it can request presence/expiry and mount them only into the exact approved workload identity.

7.2 Customer-owned policy

Before installer authentication, customer security installs a signed policy containing:

• customer/environment/cluster identity;
• allowed namespaces, registry repositories, release/component digests, chart digest, controller version, and levyctl range;
• storage/ingress classes, domains, data endpoints, egress destinations, network/security profile;
• evidence repository, entitlement, trust roots, revocation version, approval issuers;
• resource/capacity ceilings and enabled protection/deployment profiles;
• allowed catalogs/cohorts/change windows and failed-safe ceilings.

The installer can read only its digest, compatibility result, and typed denial reasons. It cannot create, patch, replace, or select a different policy.

7.3 Canonical request and immutability

The complete installation or upgrade request is canonical JSON using UTF-8 and RFC 8785 JSON Canonicalization Scheme semantics, hashed with SHA-256, and signed by the required customer and Levy approvers. The request contains no secret values. The controller:

1. validates schema and rejects unknown fields;
2. verifies issuer, signature, nonce, expiry, customer/environment, release, configuration, entitlement, and policy digests;
3. re-derives every target from the customer policy and rejects a mismatch;
4. generates the Kubernetes custom resource itself;
5. uses CRD validation/CEL to make spec immutable;
6. has admission independently recheck namespace, image digest, security context, mounts, command/entrypoint, service account, and network targets;
7. records the exact request/created-object digests before mutation.

A changed field requires a new request ID, nonce, digest, signatures, dry-run plan, and approval. No patch-in-place path exists.

The generated LevyInstallationRequest CRD has only these top-level spec fields:

Its status exposes only controller-owned fields:

The CR contains no source, chart/rendered manifests, command/args/env, Secret reference locations, raw dependency responses, logs/events, consumer data, database results, or installer-editable status. Kubernetes watch/read of the CR remains denied to the installer; only the controller API renders the permitted typed subset.

7.4 Reconciliation state machine

Normative top-level states:

Draft
  -> Validating
  -> Planned
  -> AwaitingApproval
  -> PreMutationCheck
  -> Migrating
  -> Deploying
  -> Verifying
  -> ReadyForIntegration
  -> AcceptanceInProgress
  -> Accepted

Any mutable state
  -> FailedSafe
  -> RollingBack | ForwardFixRequired | RestoreRequired | ExternalPrerequisite
  -> RolledBack | Resolved

State rules:

• transitions are monotonic except through a declared recovery edge;
• one mutation may be active per customer/environment;
• reconcile is idempotent after controller restart or duplicate submission;
• every external action has an operation ID and before/after receipt;
• a stage cannot advance until its declared invariants pass;
• cancellation uses only release-declared safe points and never discards an in-flight ride, financial, webhook, or device intent;
• FailedSafe records what changed, safe-state assertion, owning role, recovery class, deadline, and automatic action;
• the 4-hour pre-mutation and 24-hour post-migration/prelive ceilings are termination deadlines for active operations, not deadlines for a person or provider to resolve the cause. At expiry the controller takes the release-declared safe action, emits a terminal non-mutating result, and requires a new request to resume;
• AwaitingApproval and ExternalPrerequisite are dormant, non-mutating states excluded from those active-operation ceilings. Their case, session, approval, entitlement, and change-window expirations still apply and force terminal expiry without mutation;
• active safety/financial/residency incidents invoke immediate containment and a rollback decision within 30 minutes;
• terminal acceptance requires the complete evidence index, approvals, fixture disposition, and installer-access closure.

7.5 Redaction contract

Controller API responses are constructed from typed fields, not scrubbed raw logs. Allowed fields include operation/check IDs, component aliases, timestamps, status enum, expected/observed enum or bounded numeric measurement, digest, redacted provider code, correlation ID, owner, runbook ID, and recovery class.

Responses never include source, manifest bodies, image paths/layers, commands, environment values, secret names when sensitive, secret values, stack traces, arbitrary dependency text, SQL, database results, consumer identifiers, GPS coordinates, OTPs, tokens, payment instruments, identity documents, or raw network payloads. Unexpected exceptions map to an allowlisted error code; raw detail remains customer-restricted and is never proxied to the installer.

7.6 Controller lifecycle

The customer—not the installer—owns controller bootstrap, replacement, upgrade, and rollback. docs/runbooks/onprem/controller-lifecycle.md defines a signed bootstrap bundle, controller/CRD/OpenAPI/admission digests, supported server and levyctl ranges, CRD conversion strategy, stored-version migration, and maximum skew. Replacement is refused while a mutating case is open. Customer platform/security applies the new signed bootstrap, verifies /system/version, conversion and reconciliation health, and records a lifecycle receipt before installer access is re-enabled. Controller rollback is allowed only when the prior controller supports every stored CRD version and active runtime release; otherwise the runbook requires forward fix. A controller lifecycle change that alters request, security, evidence, or recovery semantics requires D3 qualification and affected-scope D4 recertification.

8. Normative installer API and CLI contract

8.1 Transport and authentication

• Base path: /installer/v1 over TLS 1.2+ with customer-issued server certificate.
• Authentication: customer OIDC access token plus mTLS when required by site policy.
• Token audience: installation controller only; maximum lifetime 60 minutes.
• Token binding: installer subject, customer, environment, case, allowed verb set, session, issued-at, expiry, and optional client-certificate thumbprint.
• Requests: application/json, UTF-8, strict schema, maximum size per endpoint, unknown fields rejected.
• Evidence-writing and state-mutating requests use the signed envelopes in Section 8.2.2; transport alone never supplies authority.
• Every response: requestId, operationId where applicable, timestamp, status, code, receiptId, auditCorrelationId.
• No API route proxies Kubernetes, registry, database, provider, object-store, backup, log, event, shell, URL-fetch, or arbitrary command behavior.

8.2 Endpoint set

The endpoint set is closed. The OpenAPI document generated under deploy/onprem/installer-api-contract/ must expose only:

No generic /jobs, /commands, /manifests, /logs, /events, /proxy, /exec, /debug, /query, /files, /images, /secrets, or user-supplied URL endpoint exists.

Endpoint classifications are normative:

• readOnly: GET /system/version, release-receipt, operation-status, and receipt-read routes. The envelope requires authenticated customer/environment/case binding where applicable, request ID, issue/expiry, and the exact resource ID; it cannot create evidence or change state.
• evidenceWriting: access verification, preflight, configuration validation, plans, verifications, rollout observations, support bundles, acceptance assembly/verification, and case initialization. The envelope additionally requires nonce, idempotency key, canonical envelope digest, catalog/reference digest, and any catalog-specific fixture/support/data approval. It may append receipts and execute only catalog-declared, bounded, immutable-ID synthetic/diagnostic effects that are fixture-disposition controlled; it cannot change release/configuration, deployment topology, live rollout, or arbitrary application/runtime state.
• stateMutating: installation, upgrade, rollback, cancellation, rollout advancement, and fixture disposition. The envelope additionally requires target-policy reference and the complete purpose-specific customer/Levy approval and detached-signature set.

OpenAPI marks every operation with exactly one classification and tests prove that an evidence-writing handler cannot exceed its signed catalog effects or change release/configuration, deployment topology, or live rollout.

8.2.1 Local-only CLI commands

These commands perform deterministic validation on installer-visible files and do not call Kubernetes, registry, database, secret manager, provider administration, or an arbitrary URL:

package verify must validate the Release Package Contract index, every file digest/schema/cross-reference/signature/freshness/compatibility rule, and prohibited placeholder/secret/source/endpoint content. Local commands accept only local paths under the approved workspace/evidence mounts, reject symlinks/path traversal/device files, never execute package content, and do not emit raw file bodies in errors.

8.2.2 Request and response bodies

All case-bound API requests carry caseId, customerId, environmentId, requestId, issuedAt, expiresAt, and clientProtocolVersion. /system/version is customer-authenticated but not case-bound. POST /cases is the case-bootstrap endpoint: it carries customer/environment/package/evidence bindings and returns the immutable case ID and receipt used by every subsequent case-bound request. Read-only requests additionally name only the exact resource/receipt/operation ID. Evidence-writing requests add nonce, idempotencyKey, canonicalEnvelopeDigest, and their signed catalog/document refs; where a catalog creates fixtures they also add installationFixtureId and its approval. State-mutating requests add targetPolicyRef, every required approvalRef, and the detached full-envelope signature set.

Endpoint-specific bodies are limited to:

Successful responses contain only the common response envelope plus the endpoint's typed receipt/operation/resource reference and bounded status fields. Denials contain status: "denied", stable code, owner/runbook where safe, and audit correlation; they do not reveal whether an unauthorized target resource exists.

8.3 Rate and concurrency defaults

Release/site policy may lower but not raise these without a new security review:

• one active mutating operation per customer/environment;
• five concurrent read-only/evidence verification operations per case and one concurrent operation per catalog;
• 60 read requests per minute per principal and 300 per case;
• 10 mutation attempts per hour per case;
• request body maximum 256 KiB; receipt response maximum 1 MiB;
• typed event stream maximum 10 events/second and 10,000 events/operation;
• repeated denial/replay threshold of five in ten minutes locks the principal pending customer-security review;
• endpoint timeout is release-defined; it cannot exceed the failed-safe ceilings in Section 7.4.

8.4 Stable result and exit codes

HTTP communicates transport; the body communicates the operational result. The CLI exits:

The same failure returns the same class regardless of human-readable wording. Unknown/unmapped server errors become FAIL_RELEASE or FAIL_SECURITY according to the component boundary and never return raw details.

8.5 Compatibility

• API major versions are isolated by path.
• Additive optional response fields require a minor version and must be ignored safely by compatible clients.
• New request fields default to rejected until both CLI and controller advertise the exact schema.
• Removing/changing a field, enum meaning, signature input, state transition, or security rule requires a new major version.
• Every release index declares server, controller, CLI, schema, mobile, gateway, baseline, and N-1 compatibility ranges.
• A CLI outside the declared range refuses before mutation.

9. Schema and signing rules

Release Package Contract owns the detailed fields. All machine-readable artifacts share these rules:

• JSON Schema 2020-12, UTF-8, no duplicate keys, unknown fields rejected unless a schema explicitly declares an extension object;
• canonicalization with RFC 8785 semantics before SHA-256 digest; envelopeDigest covers the complete Release Package Contract signed-envelope projection with only envelopeDigest and signatures removed;
• immutable IDs use lowercase ASCII [a-z0-9][a-z0-9._-]{2,127} and are never reassigned;
• timestamps use UTC RFC 3339 with seconds and Z; clocks outside the signed skew tolerance fail;
• durations use ISO 8601 or a schema-specific integer seconds field, never free text;
• digests use <algorithm>:<lowercase-hex> and release 1 supports sha256;
• signatures include crypto profile, algorithm, key ID, signer role, signed-at, expiry when applicable, target document ID/type, envelope digest, and signature bytes; the signature covers that RFC 8785-canonicalized claim with only signature bytes removed, and trust policy independently maps key ID to authoritative role;
• secrets are represented only as opaque reference IDs with owner/provider/purpose/rotation metadata;
• money uses ISO 4217 currency plus signed integer minor units; floating point is prohibited;
• geographic points use WGS84 decimal coordinates only inside operational stores, never installer receipts; evidence uses region/zone IDs and aggregate counts;
• every artifact includes schemaVersion, documentType, documentId, customer/environment/release bindings (including required nulls for global documents), createdAt, createdBy, expiresAt, payloadDigest, and envelopeDigest;
• all approvals and exceptions bind the exact artifact digest and cannot authorize future or wildcard content.

10. Release and supply-chain pipeline

The release pipeline is isolated from customer runtime and performs:

1. clean, reproducible checkout and locked dependency resolution;
2. unit, contract, integration, E2E, load, resilience, upgrade, rollback, restore, authorization, and residency tests;
3. server/client builds with production profile and no secret-dependent source-map retention;
4. prohibited-source/path/host/key/fallback/debug scan of every image layer and client binary;
5. SBOM, license notices, vulnerability scan, provenance, and build-environment receipt;
6. immutable OCI image and binary digest publication;
7. generation of schemas, OpenAPI, CRD, bootstrap, admission, chart, dashboards, catalogs, and runbooks;
8. construction of aggregate release index and compatibility/support matrix;
9. signing by Levy release authority and independent verification;
10. optional customer-scoped encryption/export for offline custody;
11. import/rollback-retention rehearsal in a clean local registry;
12. D3 qualification and handoff to Installation Certification.

No artifact is rebuilt at the customer. Configuration changes select signed options/references; they do not compile customer-specific server source.

11. Test and verification matrix

Flaky or quarantined tests cannot satisfy a release gate. A signed exception must name the exact test, reason, compensating control, owner, expiration, affected customer/release, and prohibition on expansion.

12. Release assembly and qualification

Release assembly freezes the versioned API and schema contracts, builds the native-local services and clients, produces the signed runtime and delivery-control artifacts, executes the complete verification matrix, and emits the customer-ready package defined by the Release Package Contract.

No artifact is rebuilt at the customer site. Configuration selects signed options and customer-owned service references without compiling customer-specific server source. The exact release, controller, CLI, custody tools, schema set, platform profile, and certification receipt remain digest-bound throughout installation and acceptance.

13. Program controls and decision ownership

13.1 Required decision records

Architecture decisions are required for:

• reference Kubernetes/database/object/identity/observability distributions and version policy;
• native baseline schema and tenant/authorization model;
• payment/messaging/IoT contract versions;
• operator/rider identity/token formats;
• job transport and lease/fencing rules;
• controller identity split, CRD, admission, signature, canonicalization, and trust roots;
• OCI signing/custody/encryption and key rotation/revocation;
• entitlement binding/capacity/recovery behavior;
• evidence repository/counter-signing/redaction;
• mobile distribution/update/attestation choices;
• support AI isolation and data-minimization boundary;
• compatibility and LTS/EOL policy.

Each record names alternatives, decision, consequences, migration path, test that proves it, and owner. A customer-specific preference cannot silently override a locked record; it creates a new supported profile or is declined.

13.2 Change control

Changes are classified:

• Class A: safety, money, auth, tenant isolation, signing, entitlement safety, controller authorization, evidence integrity—two reviewers plus domain/security owner and complete regression catalog.
• Class B: schema/API/gateway/mobile/controller compatibility—compatibility review, migration plan, N-1 tests.
• Class C: deployment/capacity/observability/runbook—platform/operations review and affected lifecycle tests.
• Class D: explanatory documentation with no behavior change—technical review and link/consistency checks.

Release exceptions cannot waive Class A invariants, source-delivery restrictions, signature verification, installer Kubernetes denial, active-ride end/lock, financial idempotency/reconciliation, backup restore proof, or residency approval.

14. Engineering definition of done

Every released work item satisfies these controls:

1. code is merged behind the correct profile/interface without a customer fork;
2. schemas and compatibility impacts are versioned;
3. unit, contract, integration, negative, and applicable E2E tests pass;
4. security, privacy/residency, safety, money, idempotency, failure, and rollback behavior are covered as applicable;
5. telemetry is local, useful, redacted, and linked to a runbook;
6. secrets/configuration use references and no prohibited fallback exists;
7. release packaging includes the output and source-exclusion scan;
8. an operator and installer diagnostic path exists without raw privileged access;
9. documentation, runbook, compatibility matrix, and traceability IDs are updated;
10. the release qualification harness can prove the feature in a clean environment.

15. Program completion criteria

Every released Levy Core On-Prem package satisfies all of the following:

1. WP-01 through WP-15 are implemented with no unresolved blocking test or exception.
2. Every Platform Architecture required core feature and enabled optional feature is implemented through native-local interfaces.
3. No production server/client/runtime artifact contains prohibited source, map, credential, debug bypass, hosted fallback, wildcard destination, or unapproved processor.
4. Empty install, synthetic prior-baseline upgrade, applicable real N-1 upgrade/application rollback, forward-fix, restore-required recovery, backup/restore, DR, and uninstall/data-disposition pass; a no-predecessor release records the real N-1 scopes as not applicable without skipping migration-framework tests.
5. All API/CLI/schema/controller contracts in this plan and Release Package Contract are implemented and compatibility tested.
6. Installer authorization is the closed controller API; the exhaustive Kubernetes/API denial suite passes before and after install, upgrade, and revocation.
7. All golden, financial, safety, IoT, job, mobile, residency, security, performance, and resilience suites pass.
8. Signed release, source-exclusion, SBOM, provenance, scan, trust, revocation, entitlement, custody, evidence, and runbook packages are generated reproducibly.
9. Release Package Contract can generate a customer release/site package with no unresolved placeholder or secret value.
10. Installation Certification achieves two consecutive cold-install certifications on clean environments for every required release/profile scope. A no-predecessor first release may omit N-1/application rollback only as explicitly scoped; its first successor must certify those scopes before D5.
11. Installation Guide can be executed by a certified third party using only the distributed package and documented support/escalation channels.
12. Documentation Overview traceability shows every requirement implemented, tested, documented, packaged, and evidenced.

16. Explicit non-shortcuts

The following do not satisfy this specification:

• substituting a hosted-production image with changed environment variables;
• shipping a Helm chart while the installer has namespace or registry access;
• retaining hosted Supabase/auth/storage/realtime as an undisclosed dependency;
• treating Stripe/Twilio interfaces as the generic local gateway contract;
• using minification/obfuscation as a promise that executable bytes cannot be inspected;
• allowing direct mobile database access in a “temporary” production profile;
• using mutable tags, unsigned overlays, manual SQL, ad hoc Jobs, raw manifests, or shell access during installation;
• accepting a backup without an isolated restore;
• accepting sandbox payments without timeout/webhook/settlement reconciliation;
• opening real riders before the strict staff-only settlement gate;
• omitting fixture marking/disposition from production tests;
• treating documentation review, CI success, or a first-party assisted lab install as independent cold-install certification.