OfflineKit Architecture

Verified against commit 942a18727c (2026-09-26). Re-verify with: dotnet test src/OfflineKit/__Tests/StellaOps.OfflineKit.WebService.Tests/StellaOps.OfflineKit.WebService.Tests.csproj (a database test suite; needs Docker for Testcontainers) and grep -n 'offlinekit' devops/release/bundle/docker-compose.yml. src/ is the source of truth; where this page and the code disagree, the code wins.

OfflineKit is the consolidated offline-exchange service of Stella Ops: one deployable family that produces signed bundles out of an estate (the export plane) and takes signed carriers in (the custody/import plane). It absorbed the Export Center service, the Mirror creator and the two AirGap posture hosts. The predecessor dossier is frozen at docs-archive/modules/export-center/architecture.md and describes hosts that no longer run.

1. Purpose and boundaries

• Owns: export profiles, runs, inputs, distributions and attestations; audit-bundle, exception-report and risk-bundle jobs; carrier custody (quarantine, content-addressed store, import ledger) and the per-part activation ledger.
• Reads, never stores: environment posture. The airgap-seal and time-anchor documents live in Platform’s environment-state custodian (platform.environment_state); OfflineKit replicates and interprets them (src/__Libraries/StellaOps.AirGap.Policy, posture classes in Posture/AirGapSealDocument.cs and Posture/AirGapTimeAnchorDocument.cs).
• Never activates domain content itself. A verified carrier is custody only. Parts are handed to their owning service through that service’s bounded API (Scanner, Vulnerabilities); OfflineKit never writes to a sibling database.
• Retired predecessors: export-web / export-worker are frozen at src/__Obsoleted/ExportCenter/; airgap-controller / airgap-time at src/__Obsoleted/AirGap/. The predecessor database stellaops_exportcenter was dropped after parity verification (see ../export-center/README.md).
• Library placement: the StellaOps.AirGap.{Bundle,Importer,Time.Verification}, StellaOps.OfflineKit.{Persistence,TrustBundle.Contracts} and StellaOps.ExportCenter.* libraries live under src/OfflineKit/__Libraries/; the domain-neutral StellaOps.AirGap.Policy lives under src/__Libraries/. StellaOps.AirGap.Sync was withdrawn on 2026-09-14 (EA-8) and StellaOps.Mirror.Creator (project StellaOps.Mirror.Creator.Core, a fail-closed creator service with no consumer) on 2026-09-26, both to src/__Obsoleted/OfflineKit/__Libraries/. The StellaOps.ExportCenter.* namespaces were kept on purpose: the lift was byte-identical.

Exception-report application withdrawal (DIP-36 / OD-1)

Exception reports cover Policy exceptions and optional exception history. The includeApplications request member and application output are withdrawn with Policy’s unused application repository. OfflineKit migration 015 removes the persisted include_applications bit; it does not remove report contents or tenant ownership. The Policy-owned exception/history API reader and deployment acceptance are tracked by PCD-871. Source tests and generated OpenAPI do not establish live acceptance.

PCD-871 supplies the tenant-bound exception-report reader. The local estate enables it in the existing ok5 service profile. Its dedicated Authority reader client has only policy:read, an allowlist and no singular tenant pin; both caller and outbound read identities bind the same authenticated tenant. Completed contents remain owned by OfflineKit and readable independently of Policy availability. Doctor/catalog identity settings are preserved.

Source verification for DIP-36: commit 394532d7114420507cb520549f9f335c9e31955d (2026-10-20). Re-verify the named native controls and generated OpenAPI; the deployment receipt is separate.

2. Runtime topology

Both roles converge the same database on startup; the migration runner serialises through an advisory lock.

• Database: stellaops_offlinekit, one role. Connection resolves only from STELLAOPS_POSTGRES_OFFLINEKIT_CONNECTION (or the configuration key Postgres:OfflineKit:ConnectionString) and fails closed otherwise (src/OfflineKit/__Libraries/StellaOps.OfflineKit.Persistence/Extensions/ConsolidatedOfflineKitPersistenceExtensions.cs).
• Schemas: offlinekit (custody, part ledger, activation history, migration ledger), export_center (the export engine), export_center_app (tenant-isolation functions the engine’s row-level security calls), catalog_replica and eventing (the tenants and environment-state replicas, converged by the replication seams from src/__Libraries/StellaOps.Catalog.Replication and src/__Libraries/StellaOps.Eventing.Reliability).
• Migrations: embedded SQL under src/OfflineKit/__Libraries/StellaOps.OfflineKit.Persistence/Migrations/, applied by AddStartupMigrations, forward-only (ADR-004). The chain contains files 001 to 014 at source 5afa95c916 (2026-10-06); 013 retires bundle_versions and 014 adds the export-run tenant registry described in section 6.
• Gateway prefix: the router resolves ^/api/offlinekit/v1(.*) to this host by its HELLO name offlinekit (OfflineKitSchemaTopology.RouterServiceName). One process publishes one name; the predecessor name exportcenter and its bare /v1/exports paths are gone. The identity envelope signed by the gateway is the host’s identity source after the route swap, so Router:IdentityEnvelopeSigningKey is mandatory in the overlay.
• Volumes. The repository overlay devops/compose/docker-compose.offlinekit-consolidated.yml (included by docker-compose.stella-ops.yml) names them compose_offlinekit-data and compose_exportcenter-object-store-data; the release bundle (devops/release/bundle/docker-compose.yml) names them ${STELLA_VOLUME_PREFIX:-stellaops}_offlinekit-data and ${STELLA_VOLUME_PREFIX:-stellaops}_exportcenter-object-store-data.

• Doctor: GET /doctor/offlinekit/checks, scope-gated on ops.health (policy offlinekit.ops.health). The surface runs the three standard checks (doctor.standard.db.connection, doctor.standard.db.migration-status, doctor.standard.db.size-budget), the owned-state budget check over the import CAS (doctor.standard.state.size-budget.* for state id volume:offlinekit-import-cas, budget from OFFLINEKIT_IMPORT_CAS_BUDGET_BYTES) and the family’s own checks (src/OfflineKit/StellaOps.OfflineKit.WebService/Doctor/OfflineKitDoctorChecks.cs): doctor.offlinekit.database.own-database, doctor.offlinekit.migration.sole-ledger, doctor.offlinekit.posture.not-stored-here, doctor.offlinekit.tenancy.resolution-source, doctor.offlinekit.export-engine.inventory, doctor.offlinekit.gateway.envelope-identity, doctor.offlinekit.gateway.router-registration, doctor.offlinekit.retention.partition-runway, doctor.offlinekit.retention.bounded-state-budgets, doctor.offlinekit.retention.mirror-cursor-budget. Two further owned-state measurements cover the export volume (OfflineKitExportOwnedStateMeasurer): volume:exportcenter-object-store-data (root OfflineKit:OwnedState:ExportVolumeRoot, default /var/lib/stella/exportcenter) and volume:offlinekit-export-runs (Export:Runs:StorageRoot), reported as doctor.standard.state.size-budget.volume-exportcenter-object-store-data and doctor.standard.state.size-budget.volume-offlinekit-export-runs; see operations/export-storage-measurement.md. Registration with the Platform doctor registry is opt-in (Doctor:Registration:Enabled, default off in both compose files).
• Service identity: OfflineKit:ServiceIdentity:{Authority,TokenEndpoint,ClientId,ClientSecret} is required, and must not be blank, whenever doctor registration or either catalog replica is enabled. The overlay binds it to the stellaops-offlinekit-doctor client.

3. Planes

The web host serves two planes that look alike and are not (src/OfflineKit/StellaOps.OfflineKit.WebService/Program.cs). The generated route reference is api-reference.md, rendered from openapi/v1.json — the document the host serves at /openapi/v1.json and the gateway aggregate lists as offlinekit (tools/scripts/docs/regen-from-openapi.ps1 -Service offlinekit, SPRINT_20260914_002 EA-6).

3.1 Export plane

The lifted Export Center application (src/OfflineKit/__Libraries/StellaOps.ExportCenter.Application) is mounted as a group at /api/offlinekit; every endpoint extension carries its own /v1/... prefix, so the served paths are:

Authorization is per endpoint: export.viewer for reads, export.operator for profile writes and run start/cancel, export.admin for profile archive (StellaOpsResourceServerPolicies.ExportViewer/ExportOperator/ExportAdmin). There is no global fallback policy; the predecessor’s fallback would have blocked the custody plane and the readiness probe. The tenant middleware is applied to /api/offlinekit except the four custody routes, and tenants resolve from the local catalog replica (Catalog:Replication:Tenants, replica-only resolver: a disabled replica fails the resolve loudly instead of answering “no such tenant”).

Two anonymous internal routes report export-adapter plugin status: GET /internal/plugins/status and POST /internal/plugins/probe. The /internal/* prefix must stay gateway-blocked.

Withdrawn export deprecation helpers (PCD-281, 2026-10-04): the old endpoint registry, sunset/header annotations and notification helpers are unsupported under the pre-release contract. Their sources and historical tests are frozen under src/__Obsoleted/OfflineKit/; the web host no longer registers their notification service. The supported export surface is the native route table above. Assurance profile metadata advertises complete /api/offlinekit/v1/exports/... HTTP paths; the owning host tests check each entry’s method and template against that table.

Withdrawal and advertised-route correction verified against c5cc6723ce. Recheck the compiled-type absence with pwsh -NoProfile -File tools/scripts/test-targeted-xunit.ps1 -Project src/OfflineKit/__Tests/StellaOps.ExportCenter.Tests/StellaOps.ExportCenter.Tests.csproj -Class "*DeprecationWithdrawalTests" -BuildProjectReferences -Restore, and the served route entries with the owning host’s ExportSurfacingClientRouteTableTests through the same wrapper.

3.2 Custody/import plane

src/OfflineKit/StellaOps.OfflineKit.WebService/Endpoints/OfflineKitEndpoints.cs maps the group /api/offlinekit/v1:

This plane resolves its tenant from the authenticated identity envelope, not from the tenants catalogue, which is why the tenant middleware excludes it: applied globally it turned a 422 digest-mismatch answer into a 403 before the verifier could say what was wrong.

3.3 Posture read

Catalog:Replication:EnvironmentState (default off) replicates Platform’s environment_state catalog into this host’s own catalog_replica schema. AirGapPostureReplicaReader answers sealed-posture and time-anchor questions from that replica, so reads keep working when Platform is down. The doctor check doctor.offlinekit.posture.not-stored-here measures that the retired airgap.state table is absent and that the custodian is platform.environment_state, class airgap-seal. The egress side of the same policy is bound from AirGap:Egress.

4. Export run engine

Source: src/OfflineKit/__Libraries/StellaOps.ExportCenter.Application/RunExecution/, src/OfflineKit/__Libraries/StellaOps.ExportCenter.WorkerRuntime/, and the Postgres repositories under src/OfflineKit/__Libraries/StellaOps.ExportCenter.Infrastructure/Postgres/Repositories/.

• Profiles. export_center.export_profiles rows carry a kind (ExportProfileKind: AdHoc=1, Scheduled=2, EventDriven=3, Continuous=4, Mirror=5), a scope_json, a format_json and a signing_json. Mirror is a profile kind, not a second engine (DC-22): there is one bundle-production engine and mirror production is one of its materialisers. Profile and format options: ../export-center/profiles.md.
• Submission. POST /api/offlinekit/v1/exports/profiles/{profileId}/runs writes an export_runs row in status Queued (statuses: Queued, Running, Completed, PartiallyCompleted, Failed, Cancelled; triggers: Manual, Scheduled, Event, Api). The web host does not execute runs.
• Lease. ExportRunWorker on offlinekit-worker (gated by Export:Runs:Worker:Enabled) first asks which tenants have Queued runs through export_center_app.tenants_with_pending_runs(status), then opens a tenant-scoped session and leases one run at a time with PostgresExportRunRepository.LeaseNextAsync: an UPDATE ... WHERE run_id = (SELECT ... FOR UPDATE SKIP LOCKED) that moves the oldest Queued run to Running. Each pass is capped per tenant (Export:Runs:Worker:MaxRunsPerTenantPerPass, default 4); the poll interval defaults to 5 s. A separate sweep (ExpirySweepInterval, default 15 min) fails Running runs that outlived their own expires_at. Shutdown leaves a leased run Running rather than requeueing it, because the process cannot know whether artifacts were already written.
• Materialisers. ExportRunExecutor creates <Export:Runs:StorageRoot>/<tenant>/<run>/ and dispatches on the profile kind:
  • DeclaredInputsExportRunMaterializer (kinds 1 to 4) reads DeclaredExportScope from scope_json: inputs[] with sourceRef, kind, name and an optional expected sha256. Inputs are read only from directories listed in Export:Runs:DeclaredInputRoots; an empty list refuses every declared input. This is a containment boundary: scope_json is operator-authored data in a tenant-scoped row. The per-run input manifest is written to export_inputs before the format adapter runs, so a failed run still records what it was asked to export. The adapter is resolved through the registry populated by AddExportAdapters.
  • MirrorExportRunMaterializer (kind 5) reads MirrorProfileScope: sources[] with sourceId, sourceUri, contentKinds[] and enabled. sourceUri must be an absolute path or a file:// URI; anything else is refused. It resumes from export_center.mirror_run_cursors and writes mirror-<runId>.tar.gz through MirrorBundleBuilder. Layout: ../export-center/mirror-bundles.md.
• Carrier (SPRINT_20260914_002 EA-1). After a materialiser succeeds, ExportRunExecutor hands the produced artifacts to ExportRunCarrierWriter, which writes the run’s OfflineKit carrier into <run>/carrier/ through the family’s own envelope library (StellaOps.AirGap.Bundle/Models/OfflineKitCarrierWriter.cs): offline-kit.tar.gz holding every artifact as a part, the canonical manifest.json (OfflineKitCarrierManifest, the one type the import parses, schemaVersion stella.ops/offlinekit-manifest@v1), bundle.dsse.json (in-toto carrier statement binding both digests), manifest.dsse.json (DSSE over the manifest bytes) and the CLI sidecar offline-kit.tar.gz.metadata.json. The five files become artifacts of kind carrier (metadata offlinekit.carrierRole) so the ledger records them and the artifact download route serves them. Parts are keyed (domain, mediaType, generation): an artifact a materialiser stamped with an owner contract (see owner-part below) activates on import; any other artifact ships as <kind>/<name> and is verified and recorded PART_ACTIVATOR_NOT_REGISTERED until a domain claims it. Signing custody is the crypto registry, key resolved by id (Export:Carrier:SigningKeyId, CryptoRegistryCarrierSigner); the lab mounts an operator EC P-256 PEM (OperatorMountedSigningKeys, the NIS2 SoA shape), production points the id at a sovereign provider. With no key id configured the run completes without a carrier and records EXPORT_RUN_CARRIER_NOT_WRITTEN on the row; a carrier that cannot be written fails the run with EXPORT_RUN_CARRIER_FAULTED.
• Owner-part inputs (EA-1). A declared-inputs profile may declare {"kind":"owner-part","sourceRef":"scanner:artifact-boms","tenant":"<slug>"}. The materialiser resolves the sourceRef through a registered IOwnerPartSource (ScannerArtifactBomOwnerPartSource pulls GET /api/internal/v1/offlinekit/artifact-boms with the Scanner exchange identity — the same stellaops-offlinekit-activator client and scanner:offlinekit:artifact-boms scope the import-side activator mints, section OfflineKit:ScannerActivation on both hosts), writes the owner’s bytes verbatim as an artifact stamped with the owner contract’s part path and key, and records the manifest row under the owner route. Owner parts never pass through a format adapter. The tenant slug is declared by the profile author because the worker holds only the run’s tenant UUID; the owner’s package names its tenant and the import re-checks it against the authenticated one.
• Distributions. Every produced artifact is recorded as an export_distributions row of kind FileSystem, status Distributed, through the tenant-scoped idempotency key (uq_export_distributions_tenant_idempotency_key), so a replayed record collapses instead of duplicating. The artifact API (/v1/exports/runs/{runId}/artifacts) is a projection over these rows; there is no separate artifacts table. retention_expires_at carries the run’s expires_at.
• Completion. Cursors are written only after a mirror run succeeds and its artifacts are durably recorded. The run ends Completed, PartiallyCompleted (some items failed) or Failed with a coded error_json.
• Attestations. DSSE export attestations and promotion-attestation assemblies persist in export_center.export_attestations and export_center.promotion_attestation_assemblies; the Ed25519 export-attestation signer is bound from Export:Attestation:Ed25519. Verification readback (.../verify, .../verify/manifest, .../verify/attestation) is served from export_verification_runs and export_verification_artifacts. Lineage and signing rules: ../export-center/provenance-and-signing.md, reproducibility rules: ../export-center/determinism.md.
• Other loops. The audit-bundle background worker is hosted by offlinekit-web (registered with the Postgres job handler inside the export runtime composition); the risk-bundle worker (RiskBundles:Enabled) and the DevPortal-offline job (DevPortalOffline:Enabled) are hosted by offlinekit-worker. All three job families carry a NOT NULL tenant-scoped idempotency_key, so an at-least-once submission returns the existing job.
• Risk-bundle activation. AddRiskBundleWorkerLoop (StellaOps.ExportCenter.WorkerRuntime) composes the risk-bundle loop only when RiskBundles:Enabled is true. Disabled, which is the shipped default, the worker registers no signer, object store, job or hosted loop, so RiskBundles:Signing:Key and RiskBundles:Storage:RootPath are not required and a fresh install starts. Enabled, both are validated when the host starts, and a missing value fails the start with RiskBundles:Signing:Key must be configured. or RiskBundles:Storage:RootPath must be configured. There is no unsigned risk-bundle mode.

5. Import pipeline

Source: src/OfflineKit/StellaOps.OfflineKit.WebService/Imports/. Envelope model: OfflineKitCarrierManifest in src/OfflineKit/__Libraries/StellaOps.AirGap.Bundle/Models/OfflineKitCarrierManifest.cs (bundle{version,bundleId,channel,kind,capturedAt,isDelta,baseBundleId,releaseManifestSha256,producer} plus artifacts[]{name,sha256,size,domain,mediaType,generation}).

1. Carrier. POST /import is multipart: the bundle archive, the manifest JSON, a DSSE envelope over the bundle and a DSSE envelope over the manifest. Size caps come from OfflineKit:Import:Max{Bundle,Manifest,Signature,DecodedSignature}Bytes; concurrency from OfflineKit:Import:MaxConcurrentImports (1 to 8). Multipart buffering is pinned inside the custody volume (multipart-buffer/), never the process temp path.
2. Verification. Parts land in a private quarantine directory. Both envelopes are verified by OfflineKitDsseVerifier against the operator public key at OfflineKit:Import:TrustedPublicKeyPath (ES256 or PS256, SHA-256 digests, optional TrustedKeyId pin). The key must exist at startup (OfflineKitImportTrustStartupValidator); a key carried by the upload is never trusted. Manifest shape and every artifact’s (domain, mediaType, generation) triple are validated against the owner contracts before anything is promoted.
3. Posture gate (OfflineKitImportPostureGate). Read from the posture replica: posture not declared or unsealed admits; posture unreadable admits with a logged warning (a replica outage must not strand a sealed estate’s only supply path); posture sealed runs the freshness gate and fails closed with 409 when no trusted time anchor is declared, the anchor cannot be read, or the anchor has breached the seal document’s staleness budget. Import is the sanctioned ingress of a sealed estate; it is freshness-gated, never blocked outright.
4. Custody. The verified carrier is promoted from quarantine into the content-addressed store under OfflineKit:Import:StorageRoot/cas/ and recorded verified in offlinekit.bundle_imports (tenant-scoped idempotency key, both envelope bytes, the trust anchor’s SPKI digest, the CAS object key). Rejected bytes are deleted from quarantine and never enter the ledger or CAS. Carrier identity is semantic: the first canonical DSSE evidence in CAS wins and a re-signed retry reuses it. The CAS write pause (OfflineKitImportCasWritePause) refuses promotion once the CAS budget is exhausted (operations/import-cas-capacity-guard.md).
5. Parts and activators. OfflineKitPartExtractor walks the archive once for every declared part a registered IOfflineKitPartActivator claims; OfflineKitPartActivatorRegistry refuses to compose when two activators claim one triple. Each part is recorded quarantined, then staged, and ends activated, failed or superseded (owner considered it and declined) in offlinekit.bundle_import_parts, with the trail in bundle_import_part_events. A part no activator claims is failed with PART_ACTIVATOR_NOT_REGISTERED while the carrier stays verified: custody and activation are separate verdicts. Registered owners:

Activators authenticate as the stellaops-offlinekit-activator client with client credentials from OfflineKit:ScannerActivation and OfflineKit:VulnerabilitiesActivation ({Scanner,Vulnerabilities}BaseAddress, Authority, TokenEndpoint) plus the secret in OFFLINEKIT_ACTIVATOR_AUTHORITY_CLIENT_SECRET, read from the process environment. The repository overlay supplies it through .local-secrets/offlinekit-activator-authority.env; the release bundle passes the same .env value to authority, offlinekit-web and offlinekit-worker.

The release installer’s offline vulnerability-data seed (SPRINT_20260925_004 DAY-7, devops/release/bundle/install.sh step 8b) does not use this pipeline: the installer mints a token for the same activator client and posts the seed straight to the hub’s import route. 6. Ledgers and status. /status reports the latest verified carrier and parts[]; contentActivated is derived from parts and never from the carrier verdict. bundle_version_history is the append-audit table reserved for activation history. The service does not enforce import version monotonicity server-side: VersionMonotonicityChecker is used by the CLI with its file-based version store, and no OfflineKit host registers a version store. The baseline’s bundle_versions table, which claimed that gate and which nothing wrote or read, is retired by 013 (guarded: a populated table stops startup with SQLSTATE 55000). CAS promotion and the ledger write are not one transaction: on a ledger failure after promotion the CAS object is retained and status reports only ledger-backed custody.

Per-part content addressing (SPRINT_20260914_002 EA-3). After the carrier is promoted, every part a registered activator claims is stored ONCE by its own digest under <OfflineKit:Import:StorageRoot>/cas/parts/sha256/<xx>/<digest> (OfflineKitImportStorage.StorePartAsync: re-hashed on write, staged through the quarantine so the capacity pause measures it, moved into place, a concurrent writer of the same address loses harmlessly). Two carriers declaring the same bytes share one file; the carrier object under cas/sha256/<carrierDigest>/ stays as custody evidence. The part’s ledger row records the address in bundle_import_parts.cas_part_key (migration 010, nullable: rows written before EA-3 and never-claimed parts carry none), and POST /api/offlinekit/v1/imports/{importId}/parts/{domain}/activate re-reads the bytes, re-hashes them against the row’s signed declaration and re-offers them to the owner through the same staged → activated / superseded / failed lifecycle — the part is verifiable and re-activatable without the carrier that delivered it. Only a failed or superseded part is re-offered; an activated part is terminal (409 PART_ALREADY_ACTIVATED), as the ledger’s forward-only rule requires. The doctor measurer (volume:offlinekit-import-cas) walks cas/ whole, so its byte count reflects one copy per part.

6. Data model

All tables below are created by the embedded migrations. Row-level security keys off app.current_tenant through export_center_app.require_current_tenant() (uuid tenants) and offlinekit.require_current_tenant() (text tenants); both fail loudly when the session set no tenant. Retention classes are recorded as table comments and measured by the doctor checks.

export_center (baseline 001, cursors 007):

export_center_app: no tables; require_current_tenant(), update_updated_at(), register_export_run_tenant() and tenants_with_pending_runs(status).

Migration 014 corrects the applied 007 function’s FORCE-RLS assumption without editing its SQL. SECURITY DEFINER does not exempt a NOBYPASSRLS table owner from FORCE policies. Enumeration now reads registry keys and tests the requested status under each tenant’s bound context, then restores the caller’s context. The forward startup backfill takes an exclusive run-table lock and temporarily lifts FORCE only if it was already set; it restores that posture before the migration transaction and ledger commit. The owner never gains BYPASSRLS. The shipped table posture is otherwise preserved. Fresh and upgrade tests exercise this through the real PostgresExportRunRepository under a NOSUPERUSER NOBYPASSRLS owner.

offlinekit (baseline 001, custody 002, parts 003, states 008; 013 retires bundle_versions):

Incident retention (SPRINT_20260916_001 RFC-17, 2026-09-23). export_incidents carried a source-of-truth label from 001, but its manager has always deleted resolved incidents, so the P13 census read it as operational state by shape with no proven obligations. Before RFC-17 the count cap ranked every incident, so more than MaxStoredIncidents incidents in total made the next read delete the least recently updated ones, open or resolved. Both branches are now terminal-only, the budget is bound from Export:Retention:Incidents:*, and the Doctor budget check measures an incidents family. Re-verify:

pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/OfflineKit/__Tests/StellaOps.ExportCenter.Tests/StellaOps.ExportCenter.Tests.csproj -Class "*ExportIncidentRetentionTests" -BuildProjectReferences
pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/OfflineKit/__Tests/StellaOps.OfflineKit.WebService.Tests/StellaOps.OfflineKit.WebService.Tests.csproj -Method "*RetentionBudgets*" -BuildProjectReferences
python tools/scripts/validate/check-p13-retention.py --repo-root . --tables

Migrations 004, 005, 009, 011 and 012 only correct retention-class comments; applied SQL is never edited (ADR-004). The airgap schema and the predecessor’s private export_schema_version ledger are not reproduced; the standard startup-migration ledger lives in the offlinekit schema and doctor.offlinekit.migration.sole-ledger measures that it is the only one.

7. Configuration

Keys are shown in configuration form; the overlay devops/compose/docker-compose.offlinekit-consolidated.yml spells them with __ separators and maps shell variables onto them as noted.

Database and identity

Import custody (web)

Export plane (web)

Worker

8. Security and custody

• Identity. After the route swap the gateway-signed identity envelope is the web host’s only identity source, and the envelope middleware does not fail closed without a key. The overlay therefore requires the signing key, and doctor.offlinekit.gateway.envelope-identity measures the key side while the host wires the middleware side.
• Scopes. Export plane: export.viewer, export.operator, export.admin. Custody plane: airgap:import, airgap:status:read. Doctor: ops.health. Service identity: catalog:replicate and platform:doctor:register. Canonical catalogue: src/Authority/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs.
• Import trust. Carrier signatures verify only against the operator-mounted public key; the service never trusts a key carried by the upload and never falls back to its content root for storage. Sealed imports are freshness-gated against the declared trusted-time anchor.
• Signing custody. Export signing keys are operator-mounted under devops/etc/exportcenter/keys/ (git-ignored) and referenced by file path. NIS2 SoA and Assurance trust roots come from machine-local environment (STELLAOPS_EXPORTCENTER_NIS2_SOA_TRUST_ROOT_PUBLIC_KEY_PEM, STELLAOPS_EXPORTCENTER_NIS2_SOA_TRUST_ROOT_FINGERPRINT). The Signer service owns the artifact attestation keys; the kit builder receives only an entitlement proof, a DPoP key and a least-privilege client (Q-25; ../../runbooks/airgap/offlinekit-signer-custody.md). No private key material is committed.
• Isolation. One database, one role, tenant row-level security on every ledger; cross-service access is owner API only (Scanner, Vulnerabilities, EvidenceLocker, Timeline, SbomService).
• Exception-report tenant binding (PCD-871). All four exception-report routes (section 3.1) take the caller’s tenant from the authenticated principal’s stellaops:tenant claim through the tenant resolver; no header, query or body names a tenant, and a principal without one gets 400 tenant_required. Status and download read the job by tenant and job ID (ExceptionReport/ExceptionReportJobStore.cs), so another tenant’s job ID answers the same 404 as an unknown ID: no body for status, the generic report_not_found_or_not_ready error for download. A later write never moves a job to another tenant; the durable store refuses it. Verified against 7d1fc4768f; re-run pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/OfflineKit/__Tests/StellaOps.OfflineKit.WebService.Tests/StellaOps.OfflineKit.WebService.Tests.csproj -Class "*ExceptionReportTenantBindingTests".
• Bounded state. Import quarantine and multipart buffering live inside the custody volume; the CAS budget and the export retention budgets are measured by the doctor and enforced by the write pause and the prune paths.

Offline carrier test boundaries

Test source verified against 039164bd8e (PCD-360, 2026-10-04); re-run the commands below.

src/__Tests/offline/StellaOps.Offline.E2E.Tests/OfflineKitRoundTripTests.cs uses OfflineKitCarrierWriter and the serving OfflineKitDsseVerifier, replacing the withdrawn snapshot writer/reader. It checks both signed subjects, exact manifest payload binding, public-trust mismatch, unsigned-envelope refusal, archive tampering, every declared part’s bytes/digest and deterministic archive/manifest bytes. ECDSA envelope bytes are not required to be deterministic. The fixture provisions ephemeral keys through the existing crypto provider and purpose resolver; only public trust is written to disk.

This local artifact round-trip does not claim host or database acceptance. The owner’s OfflineKitImportEndpointsTests separately runs the shared writer’s carrier through the HTTP import, real PostgreSQL custody ledger and the owner activation seam. Re-run the complete Offline.E2E and AirGap.Bundle test projects with the canonical tools/scripts/test-targeted-xunit.ps1 -All -BuildProjectReferences -Restore wrapper, then run StellaOps.OfflineKit.WebService.Tests with -Class "*OfflineKitImportEndpointsTests" -BuildProjectReferences -Restore.

9. Design record

• DC-18, DC-21, DC-22 in the design-challenges register: the unified carrier envelope (DC-18), envelope authority as an evolution of AirGap.Bundle rather than a parallel format (DC-21), and one bundle-production engine with mirror as a profile kind (DC-22).
• Consolidation design (frozen): schema dispositions, the data move and the posture ruling that left posture with Platform.
• ADR-039 database-per-service ownership, ADR-004 forward-only migrations, database ownership matrix.

10. Related documents

• README.md: the family overview and the part-activation seam.
• Format records under ../export-center/: profiles.md, determinism.md, provenance-and-signing.md, mirror-bundles.md, devportal-offline.md, registry-compatibility.md, timestamp-trust-bundle-v1.md, cli.md, operations/.
• Export storage measurement: operations/export-storage-measurement.md.
• Operator guide: ../../OFFLINE_KIT.md.
• Runbooks: ../../runbooks/airgap/, in particular offlinekit-import.md (the operator import path, exit codes and the posture gate), signer custody, the OK-6 route swap and the OK-9 staged stack.
• Capacity guard: operations/import-cas-capacity-guard.md.
• Neighbours: Platform (environment-state custodian), Scanner and Vulnerabilities (part owners), Signer (attestation keys), AirGap (sealed and offline operation) and Mirror (retained format records).