# DevPortal Offline Bundle Manifest (draft v0.1)

Applies to sprint: SPRINT_0206_0001_0001_devportal · Action #2 (DEVPORT-64-001/64-002 interlock with Export Center)

## Purpose
- Define a deterministic, air-gap-friendly manifest for Developer Portal offline bundles.
- Ensure SDK archives, OpenAPI specs, and static site assets can be verified and consumed by Export Center and SDK Release pipelines.

## Bundle layout
```
devportal-offline/
  manifest.json              # see schema below
  site/                      # static HTML/CSS/JS (Astro/Starlight build)
  specs/
    stella-aggregate.yaml    # merged OpenAPI used by portal
    *.yaml                   # per-service OpenAPI (authority, scanner, policy, graph, etc.)
  sdks/
    node-sdk.tar.gz
    python-sdk.tar.gz
    java-sdk.zip             # optional, language-dependent
  assets/
    fonts/*                  # self-hosted; no external CDNs
    icons/*                  # SVG/PNG used by site
```

## Manifest schema (manifest.json)
```json
{
  "version": "0.1",
  "generatedAt": "2025-11-26T00:00:00Z",
  "site": {
    "path": "site",
    "sha256": "<hex>",
    "bytes": 0
  },
  "specs": [
    { "name": "stella-aggregate.yaml", "path": "specs/stella-aggregate.yaml", "sha256": "<hex>", "bytes": 0 },
    { "name": "authority.yaml", "path": "specs/authority.yaml", "sha256": "<hex>", "bytes": 0 }
  ],
  "sdks": [
    { "name": "node-sdk", "path": "sdks/node-sdk.tar.gz", "sha256": "<hex>", "bytes": 0 },
    { "name": "python-sdk", "path": "sdks/python-sdk.tar.gz", "sha256": "<hex>", "bytes": 0 }
  ],
  "checks": {
    "integrity": "sha256",
    "policy": "no-external-assets"
  }
}
```

### Rules
- `version` is additive; bump on breaking shape change.
- `sha256` is hex lowercase of the file contents.
- `bytes` is the exact byte length for deterministic validation.
- `checks.policy` documents applied constraints; default `no-external-assets` (verify no `http(s)://` fonts/scripts).

## Production contract
- Export Center expects `manifest.json` at bundle root; validates sha256/bytes before publishing.
- Offline bundle must build via `npm run build:offline` without network calls after initial `npm ci` + `npm run sync:spec`.
- Specs and SDK archives are treated as opaque; manifest carries their hashes for downstream verification.
- Record all hashes in `src/DevPortal/StellaOps.DevPortal.Site/SHA256SUMS.devportal-stubs` (or final SHA file) to keep determinism visible to docs/implplan sprints.

## Open items
- Add per-language SDK metadata (version, commit SHA) once SDKREL-64-002 finalises.
- Add optional `signatures` array (DSSE over manifest) when Authority signing profile is ready.

## How to produce locally (deterministic)
```
npm ci --ignore-scripts --no-fund --no-audit
npm run sync:spec
npm run build:offline
# compute manifest hashes using sha256sum and fill manifest.json
```

Record generated manifest in sprint evidence when produced; keep caches local to avoid external fetches.