Product Lifecycle Contract v1

Contract: stella.ops/productLifecycle@v1 Status: Active schema; 2026.9 lifecycle values approved for planning and live publication subject to endpoint/key/mailbox preflight in archived sprint SPRINT_20260430_006_DOCS_support_eol_policy.md. Sprint: SPRINT_20260430_006 Owner: Stella Ops manufacturer of record + Router Gateway owner Schema-pinning policy: Pinned per Stella minor release. Consumers MUST require the exact schemaVersion value they support and MUST NOT auto-follow a newer lifecycle schema. Deterministic fixture location: Router endpoint coverage lives under src/Router/__Tests/StellaOps.Gateway.WebService.Tests/Integration/ProductMetadataEndpointsTests.cs. The serving code is src/Router/StellaOps.Gateway.WebService/Middleware/ProductMetadataMiddleware.cs and src/Router/StellaOps.Gateway.WebService/ProductMetadata/ProductMetadataDocumentProvider.cs. Replay/offline expectations: Lifecycle documents, release-manifest lifecycle blocks, and offline-kit metadata MUST validate without external network access.

Purpose

Defines the machine-readable lifecycle shape for Stella Ops support and end-of-life (EOL) metadata. It is the contract for anyone publishing, consuming, or offline-validating Stella release-train support windows — Router gateway operators, offline-kit tooling, and downstream consumers of the public lifecycle endpoint.

The same release-train fields are consumed by:

• GET /api/v1/product/support-lifecycle (also HEAD) as served by the Router gateway ProductMetadataMiddleware before generic /api/* dispatch.
• /.well-known/stella-product-security.json support metadata (the supportPolicy.currentMinorTrains[] block, also served by ProductMetadataMiddleware).
• The signed product update manifest (stella.ops/productUpdateManifest@v1), whose supportPolicy.releaseTrain block is the authoritative source the live endpoint copies. See product-update-manifest-v1.md.
• Offline-kit lifecycle metadata and deterministic replay tooling.

Implementation note: the live lifecycle endpoint does not generate or compute lifecycle values. ProductMetadataDocumentProvider.GetSupportLifecycleJson() reads the single supportPolicy.releaseTrain record from the sealed, signature-verified release manifest and emits it verbatim. The static policy block below is hard-coded in the provider, and generatedAt is taken from the Platform:Product:GeneratedAtUtc config value (not from manifest content).

The human-readable policy is ../legal/product-support-policy.md. The EOL transition runbook is ../legal/eol-policy.md.

Schema Version Metadata

Any document carrying schemaVersion = stella.ops/productLifecycle@v1 MUST conform to the field definitions and validation rules below.

JSON Shape

{
  "schemaVersion": "stella.ops/productLifecycle@v1",
  "generatedAt": "2026-04-30T00:00:00Z",
  "policy": {
    "defaultWindowYears": 5,
    "supportAnchor": "ga-minor-release-train",
    "patchReleaseRule": "inherit-parent-minor-train-unless-explicitly-extended",
    "ltsSelectionRule": "last-stable-minor-of-calendar-year-unless-overridden",
    "eolDeprecationNoticeMonths": 12,
    "extendedSupportTier": "commercial-option-outside-baseline-cra"
  },
  "releaseTrains": [
    {
      "version": "2026.9",
      "releasedAt": "2026-09-01",
      "securitySupportUntil": "2031-09-01",
      "eolAt": "2031-09-01",
      "lts": false
    }
  ]
}

Field Definitions

Top-level fields

policy

releaseTrains[]

Validation Rules

• schemaVersion MUST equal stella.ops/productLifecycle@v1.
• policy.defaultWindowYears MUST be >= 5.
• policy.eolDeprecationNoticeMonths MUST be >= 12.
• Live documents MUST NOT contain TBD-* placeholders.
• releasedAt, securitySupportUntil, and eolAt MUST be ISO-8601 calendar dates in live documents.
• securitySupportUntil MUST be at least five years after releasedAt unless a shorter product lifetime has been explicitly approved and documented outside this v1 baseline.
• eolAt MUST be greater than or equal to securitySupportUntil.
• Exactly one release train per calendar year SHOULD have lts = true once the year’s LTS selection is made.
• Consumers MUST preserve unknown optional fields when signing or replaying a lifecycle document, but MUST NOT treat unknown fields as changing the v1 support commitment.

Release Manifest Integration

The signed product update manifest (stella.ops/productUpdateManifest@v1) MUST reference this contract when it carries support lifecycle data, and is the authoritative source the live lifecycle endpoint reads from. See product-update-manifest-v1.mdfor the full manifest contract. The manifest lifecycle block uses the following shape (field names verified against ProductMetadataDocumentProvider.LoadReleaseManifest):

{
  "supportPolicy": {
    "lifecycleSchema": "stella.ops/productLifecycle@v1",
    "releaseTrain": {
      "version": "2026.9",
      "releasedAt": "2026-09-01",
      "securitySupportUntil": "2031-09-01",
      "eolAt": "2031-09-01",
      "lts": false
    }
  }
}

The release manifest MUST copy lifecycle values from the same pinned source used to generate the public lifecycle endpoint. It MUST NOT hand-edit support dates independently of this contract. The Router gateway enforces manifest integrity at serve time: the manifest’s top-level version MUST match the running product version (Platform:Product:RunningProductVersion), and when Platform:Product:RunningImageDigest is set the manifest images[] array MUST contain that digest — otherwise the endpoint fails closed with HTTP 503.

Offline Determinism

Lifecycle JSON must be generated from release metadata committed or packaged with the release. Offline validators must be able to:

• Validate the schema version and required fields.
• Determine whether a release train is supported, security-only, or EOL using only bundled metadata.
• Compare the lifecycle block in a signed release manifest with the lifecycle endpoint payload.
• Replay historical lifecycle decisions without contacting Stella infrastructure.

Router Runtime Binding

ProductMetadataMiddleware (registered in Program.cs via app.UseMiddleware<ProductMetadataMiddleware>()) serves GET /api/v1/product/support-lifecycle from sealed, signature-verified release-manifest metadata, ahead of generic /api/* microservice dispatch. The endpoint is unauthenticated metadata served by middleware before routing/auth — no StellaOpsScopes scope gates it. The same middleware also serves /.well-known/security.txt and /.well-known/stella-product-security.json.

HTTP behaviour

• Methods: GET and HEAD are served. Any other verb returns HTTP 405 Method Not Allowed with Allow: GET, HEAD. HEAD returns headers (including Content-Length) with no body.
• Success (200 OK): Content-Type: application/json; charset=utf-8, an ETag header, and Cache-Control. The Cache-Control value is public, max-age=<CacheMaxAgeSeconds> when the configured cache age is positive, otherwise no-cache.
• ETag: a strong ETag computed as the lowercase hex SHA-256 of the exact response bytes, wrapped in double quotes ("<64-hex-chars>").
• Conditional requests: when an If-None-Match request header matches the current ETag (or is *), the endpoint returns 304 Not Modified with the ETag and Cache-Control headers and no body.
• Fail closed (503 Service Unavailable): empty body and Cache-Control: no-store, with no ETag.

Fail-closed conditions (HTTP 503)

The endpoint fails closed when TryBuildDocuments() cannot produce a verified document, including when:

• Platform:Product:PublishMetadata is false (publication disabled).
• Platform:Product:SealedConfig is false (config not sealed).
• Any of the eight operational preflight checks under Platform:Product:Preflight is incomplete (MailboxDeliveryVerified, MailboxAccessVerified, KeyFreshnessVerified, KeyFingerprintVerified, PlacementAnchorVerified, SupportLifecycleVerified, RotationVerified, EscalationVerified).
• Platform:Product:ReleaseManifestSignatureVerified is false.
• Platform:Product:GeneratedAtUtc is not a parseable timestamp.
• Platform:Product:CanonicalBaseUrl is not an absolute HTTPS URL.
• Platform:Product:ReleaseManifestPath is unset or the file is missing.
• The release manifest fails validation: wrong schemaVersion (must be stella.ops/productUpdateManifest@v1), any TBD- placeholder string anywhere in the document, manifest version does not match the running product version, the running image digest is not covered by images[], a wrong supportPolicy.lifecycleSchema (must be stella.ops/productLifecycle@v1), missing/empty required fields, or unreadable/invalid JSON.

Configuration keys (Platform:Product section)

Bound by ProductMetadataOptions.Bind; each also accepts a flattened dotted key (e.g. platform.product.publishMetadata).

Revision Log