git.stella-ops.org/docs/advisory-ai/packaging.md

Advisory AI Packaging & SBOM Bundle (AIAI-PACKAGING-31-002)

Updated: 2025-11-22 · Owner: Advisory AI Release · Status: Draft

Defines the artefacts and provenance required to ship Advisory AI in Sprint 0111, covering offline kits and on-prem deployments.

1) Bundle contents

Artefact	Purpose	Provenance
advisory-ai-web image	API surface + plan cache	SBOM: SBOM-AIAI-31-001:web; DSSE attestation signed by Release key
advisory-ai-worker image	Queue + inference executor	SBOM: SBOM-AIAI-31-001:worker; DSSE attestation
Prompt + guardrail pack	Deterministic prompts, redaction lists, validation rules	DSSE sealed; hash recorded in prompts.manifest
Profile catalog	default, fips-local, gost-local, cloud-openai (disabled)	Versioned JSON, hashed; tenant consent flags captured
Policy bundle	policyVersion digest for baseline evaluation; Authority importable	DSSE + provenance to Policy Engine digests
LNM evidence export (optional)	Concelier advisory_linksets + advisory_observations for air-gap replay	Hash list aligned to provenanceHash in RAG bundles
SBOM context client config	Example AddSbomContextHttpClient settings (BaseAddress, Endpoint, ApiKey)	Signed sbom-context.example.json

2) Directory layout (Offline Kit)

/offline-kit/advisory-ai/
  images/
    advisory-ai-web.tar.zst
    advisory-ai-worker.tar.zst
  sboms/
    SBOM-AIAI-31-001-web.json
    SBOM-AIAI-31-001-worker.json
  provenance/
    advisory-ai-web.intoto.jsonl
    advisory-ai-worker.intoto.jsonl
    prompts.manifest.dsse
    profiles.catalog.json
    policy-bundle.intoto.jsonl
  config/
    advisoryai.appsettings.example.json
    sbom-context.example.json
  evidence/
    lnm-linksets.ndjson      # optional; aligns to linkset hashes in RAG bundles
    lnm-observations.ndjson  # optional; immutable raw docs

• All files hashed into SHA256SUMS with DSSE signature (SHA256SUMS.dsse).
• Profiles catalog and prompt pack hashes must be propagated into AdvisoryAI:Provenance settings for runtime verification.

3) SBOM & provenance rules

• SBOMs must follow SPDX 3.0.1; embed image digest (sha256:<...>) and build args.
• Attestations use DSSE + SPDX predicate; signer key matches Release guild key referenced in DEVOPS-AIAI-31-001.
• For air-gapped installs, operators verify: slsa-verifier verify-attestation --source=stellaops/advisory-ai-web --bundle advisory-ai-web.intoto.jsonl --digest <image-digest>.

4) Deployment checklist

• Import advisory-ai-web and advisory-ai-worker images to registry.
• Apply profiles.catalog.json; ensure remote profiles disabled unless Authority consent granted.
• Load prompt pack and set AdvisoryAI:Prompts:ManifestHash to prompts.manifest.
• Configure SBOM client (or keep NullSbomContextClient default).
• If shipping LNM evidence, seed advisory_linksets and advisory_observations collections before enabling inference.
• Record hashes in deployment log; surface in Authority audit via advisory_ai.output.generated events.

5) Update obligations

• Any change to prompts, guardrails, or profiles → bump manifest hash and regenerate DSSE.
• SBOM updates follow the same SBOM-AIAI-31-001 idempotent contract; replace files, update SHA256SUMS, resign.
• Link all changes into the sprint Execution Log and Decisions & Risks sections.
• CLI/Policy artefacts must be present before enabling cloud-openai or default profiles for tenants; if missing, keep profiles disabled and record the reason in Decisions & Risks.