# Product Onboarding Executable Packet v1

Status: active execution packet
Owner: Platform Architecture / Product Architecture
Last updated: 2026-06-03
Fairway task: `PSSM-PROD-C3-PRODUCT-ONBOARDING-CONTRACT-001`

## Purpose

Turn the product onboarding checklist into a repeatable packet that can be
reviewed, tested, and tracked in Fairway before a product receives durable
routes, tables, events, app manifests, SDK examples, or release gates.

This packet is intentionally product-neutral. Token Factory, App Platform,
GPUaaS add-on products, and future products must use the same shared platform
contracts instead of creating product-owned IAM, billing, audit, notification,
status, policy, registry, artifact, or credential forks.

## Required Packet Shape

Every product onboarding packet must include these fields. A missing value fails
closed unless the field is explicitly marked `not_applicable` with an owner,
reason, and review date.

```yaml
product_onboarding_packet:
  packet_id: string
  product_id: string
  product_slug: string
  lifecycle_state: draft | onboarding | active | deprecated | retired
  owner:
    product: string
    engineering: string
    operations: string
    security: string
  personas:
    - user
    - operator
    - developer
    - product
    - security
  exposure:
    posture: internal | partner | external
    public_docs_track: none | internal | partner | public
  ownership:
    packages:
      - path: string
        owner: product | platform | shared
    routes:
      - family: public | admin | internal | read_model
        prefix: string
        owner: string
    schemas:
      - table_or_view: string
        owner: string
    events:
      - subject: string
        producer: string
        consumers:
          - string
    frontend_surfaces:
      - page_family: string
        owner: string
  shared_services:
    iam:
      scopes:
        - scope: string
          registry_state: draft | active | not_applicable
      roles:
        - string
      service_accounts: required | optional | not_applicable
      entitlement_rows: required | not_applicable
    billing:
      posture: billable | non_billable | deferred
      usage_units:
        - unit: string
          version: string
      resource_types:
        - string
      rating_rule: required | not_applicable
      ledger_write_owner: platform_billing
    audit:
      actions:
        - action: string
      privileged_mutations:
        - route_or_command: string
      query_surface: required | not_applicable
    notifications:
      templates:
        - template_key: string
      delivery_intents:
        - string
      escalation: required | not_applicable
    evidence_status:
      evidence_types:
        - type: string
      invariants:
        - invariant_id: string
      status_components:
        - component_id: string
      slo_posture: required | not_applicable
    policy_quota:
      policy_keys:
        - key: string
      quota_dimensions:
        - dimension: string
      snapshot_kinds:
        - kind: string
    registry_artifacts:
      product_registry_entry: required
      artifact_types:
        - type: string
      trust_requirements:
        - digest_pinned
        - provenance
        - sbom
    secrets_pki:
      credential_purposes:
        - purpose: string
      custody_tier: vault | step_ca | platform_metadata | not_applicable
      rotation_owner: string
  docs_and_portal:
    user_page: required | not_applicable
    developer_page: required | not_applicable
    operator_page: required | not_applicable
    security_page: required | not_applicable
    product_page: required | not_applicable
    architecture_page: required | not_applicable
  uat_and_release:
    contract_tests:
      - command: string
    smoke_tests:
      - command: string
    release_evidence_bundle: required
    rollback_posture: string
  extraction:
    posture: keep | split | extract
    service_auth_packet: required | not_ready | not_applicable
    degradation_contract: required | not_ready | not_applicable
```

## Fail-Closed Validation

The packet is valid only when all required shared-service contracts are present
or explicitly marked `not_applicable`.

| Validation | Fail-closed rule |
|---|---|
| Product registry | Product cannot be visible outside onboarding mode unless the product registry entry is active. |
| IAM scopes | Product routes and SDK examples cannot ship with unregistered scope strings. |
| Usage units | Billable products cannot emit accepted usage without an active usage-unit registry entry and rating posture. |
| Resource types | Product resources must use registered resource types before billing, audit, evidence, quota, or status references them. |
| Audit actions | Privileged mutations cannot be marked complete without audit-action registry entries and evidence. |
| Notification templates | Product-owned notification templates are forbidden; use platform template registry or record no-notification decision. |
| Evidence types | UAT, release, and runtime proof must use platform evidence types or a tracked missing-artifact row. |
| Status components | Product health cannot be represented only by logs or SQL; define Status/Ops component ids or record missing-artifact evidence. |
| Policy/quota | Quota-changing writes must identify snapshot kind, dimension, parent scope, and override scope. |
| Credentials | Product-specific secret custody is forbidden unless security architecture approves an exception. |
| Portal/docs | Internal developer or operator support cannot be declared ready without portal pages or a tracked doc gap. |

## Execution Stages

| Stage | Output | Exit gate |
|---|---|---|
| 0. Intake | Product identity, owners, personas, exposure, support tier | Fairway epic created with source docs and review domains |
| 1. Ownership | Package, route, schema, event, worker, frontend ownership rows | Boundary guard can classify new paths |
| 2. Registry | Product, scope, usage-unit, resource-type, audit-action, evidence-type, notification-template, artifact-type entries | Runtime visibility remains disabled until entries are active |
| 3. Contracts | API/event/SDK/app manifest contracts and failure model | Contract tests or tracked blockers exist |
| 4. Platform services | IAM, billing, audit, notification, policy/quota, evidence/status, secrets/artifacts integration | No product-owned fork of a shared service |
| 5. UAT evidence | Launch/connect/decommission, billing attribution, audit query, status read model, rollback proof | Release evidence bundle exists |
| 6. Portal | User, developer, operator, security, product, and architecture pages | Source inventory and freshness owner exist |
| 7. Extraction posture | Keep/split/extract recommendation and blockers | No extraction without service auth, rollback, smoke, and degradation evidence |

## Review Matrix

| Reviewer | Must confirm |
|---|---|
| Product | Personas, exposure, support tier, packaging, user workflows, and non-goals are clear. |
| Architecture | Product does not introduce new shared-service owners or bypass maps/guards/facades. |
| Backend | API/event contracts, service boundaries, idempotency, audit, and billing ingestion are explicit. |
| Frontend | Page family, navigation, context picker, status/error states, and portal surfaces are explicit. |
| Security | Scopes, service accounts, credential custody, audit evidence, and failure behavior are explicit. |
| Operations | Status components, SLO posture, reconciliation, DLQ/outbox, runbook, and rollback evidence are explicit. |
| Governance | Fairway tasks, evidence artifacts, residual risk, and release gates are linked. |

## Example Minimal Token Factory Packet

```yaml
product_onboarding_packet:
  packet_id: token-factory-onboarding-v1
  product_id: token-factory
  product_slug: token-factory
  lifecycle_state: draft
  shared_services:
    iam:
      scopes:
        - scope: token_factory:model:invoke
          registry_state: draft
        - scope: token_factory:key:manage
          registry_state: draft
      service_accounts: required
      entitlement_rows: required
    billing:
      posture: billable
      usage_units:
        - unit: token_input
          version: v1
        - unit: token_output
          version: v1
        - unit: request
          version: v1
      resource_types:
        - model_endpoint
        - api_key
      rating_rule: required
      ledger_write_owner: platform_billing
    policy_quota:
      quota_dimensions:
        - request_per_minute
        - token_per_day
        - spend_minor_per_month
      snapshot_kinds:
        - product_quota
        - api_key_limit
```

This example is not an implementation approval. It shows the minimum packet
shape needed before Token Factory work starts.

## Related Docs

- `Product_Onboarding_Checklist_v1.md`
- `Second_Product_Onboarding_Packet_App_SDK_JupyterLab_v1.md`
- `Platform_Registry_Contract_v1.md`
- `App_SDK_Readiness_Matrix_v1.md`
- `Notification_Policy_Portal_Surface_Model_v1.md`
- `Secrets_PKI_Runtime_Trust_Model_v1.md`
- `../Unified_IAM_Billing_Across_Products_v1.md`