# Helpifyr Boost Admission Pack — Canonical

**Version 2.1.0 · tri-mode (open source · proprietär · hybrid)**
Aligned with `JaddaHelpifyr/helpifyr-fabric@main`, dual-mode merge `e723b928` (#1277). Erstverifiziert 2026-07-15, erneut re-verifiziert 2026-08-10 gegen `jhf-fabric-platform-api :38080`.

> Dieser Pack ist die menschenlesbare Begleitung zum kanonischen Admission-Dry-Run-Schema
> (`contracts/admission/admission_dry_run_input.schema.json`). Er funktioniert **identisch für
> Open-Source-, proprietäre und hybride Boosts** — der einzige Verzweigungspunkt ist das Feld
> `integration_model`. Companion-Datei: `helpifyr_boost_admission_dry_run.canonical.template.json`
> (drei fertige, live-validierte Vorlagen zum Kopieren).

---

## 0. Was ist ein „Boost"?

Ein Boost ist eine extern betriebene Fähigkeit, die Helpifyr Fabric über **versionierte APIs und
Contracts** kontrolliert einbindet — nicht durch Code-Verschmelzung. Fabric bleibt Admission- und
Verdict-Owner; der Boost bleibt Eigentümer seines Produkts, seiner Docs und seiner Runtime. Ziel
dieses Packs: einen Boost so vorbereiten, dass die Aufnahme **fail-closed, evidenzbasiert und
wiederholbar** ist — und für dich als externen Anbieter **so einfach wie möglich**.

---

## 1. Schritt 0 — Wähle dein `integration_model`

`integration_model` ist Pflicht am Request-Root. `null` oder Weglassen ist **nicht** erlaubt (→ HTTP 422).

| Model | Wann | Pflicht-Evidence |
|---|---|---|
| `oss-repository` | Der Boost ist quelloffen; ein öffentliches Repo ist Teil der Integration | **beide** OSS-Nachweise; **kein** `proprietary_verification` |
| `proprietary-service` | Geschlossener/privater Service, kein öffentliches Repo | `proprietary_verification`; **keine** OSS-Felder erlaubt |
| `hybrid` | Öffentlicher Anteil (SDK/Docs/Client) **und** geschlossener Kern | **beide** OSS-Nachweise **und** `proprietary_verification` |

**Entscheidungshilfe:** Ist irgendein Teil des Boosts als öffentliches Repo Teil der vereinbarten
Integration? Nein → `proprietary-service`. Ja, vollständig quelloffen → `oss-repository`. Teils/teils
→ `hybrid`. Keine Offenlegung von proprietärem Quellcode wird jemals verlangt.

**Zusatzhinweis für Wissens-/Memory-/Context-Boosts:** Berührt dein Boost governed knowledge,
Context-Graph, Model-Selection oder episodisches Memory, verlangt die Onboarding-Seite zusätzlich ein
`knowledge_extension_manifest_v1`. Dieses Pack deckt nur den tri-mode Admission-Body ab — für die
Wissens-Erweiterung bitte direkt mit dem Fabric-Kontakt abstimmen. Für rein transaktionale/API-Boosts
(z. B. Buchhaltungs-, Delivery- oder Workflow-Anbindungen) ist dieser Zusatz **nicht relevant**.

---

## 2. Der kanonische Request — Felder & Pflichten

Root-Objekt (`additionalProperties: false` — unbekannte Felder ⇒ 422):

| Feld | Pflicht | Inhalt |
|---|---|---|
| `integration_model` | immer | `oss-repository` / `proprietary-service` / `hybrid` |
| `manifest_document` | immer | Provider-/Tool-Identität (siehe 2.1) |
| `docs_metadata` | immer | Docs-Einstieg + Standard-Version + Issues (+ OSS-Felder je nach Mode) |
| `proprietary_verification` | prop + hybrid | nicht-sensible Attestierung (siehe 2.3) |
| `producer_declarations` | immer (darf `[]` sein) | von dir **produzierte** Fabric-Contract-Families |
| `consumer_declarations` | immer | von dir **konsumierte** Fabric-Contract-Families |
| `compatibility` | immer | Modus + Deprecation-Window |
| `lifecycle` | immer | Status + `effective_from` |
| `verify_metadata` | immer | Verify-Pfad + Readiness-Refs + Live-Ziel |
| `learning_projection_inputs` | optional | i. d. R. `[]` |

### 2.1 `manifest_document`

- `id` (`helpifyr.<tool_key>`), `tool_key`, `name`
- `capability_class` — **eine** kanonische Klasse (Liste unten), Pflicht und wird geprüft
- `runtime_kind` (z. B. `service`), `lifecycle_stage`, `version`, `release_channel`
- `repository { url, branch }` — nur bei `oss-repository` und `hybrid`

Kanonische Capability-Classes (aus `contracts/policies/compatibility_policy.json`, v1.2.0, 14 Klassen):
`identity`, `secrets`, `delivery`, `erp-business-truth`, `project-workflow`, `retrieval-evidence`,
`voice-runtime`, `web-operator-surface`, `workflow-engineering`, `compliance-governance`,
`ecm-document-management`, `adaptive-learning`, `workspace-groupware-runtime`,
`semantic-projection-verification-harness` (neu seit v1.2.0, additiv).

### 2.2 `docs_metadata`

Immer: `docs_entrypoint`, `docs_standard_version` (aktuell `1.0.0`), `related_issue_refs` (≥1, eindeutig).
- **oss-repository / hybrid:** zusätzlich `oss_inventory_doc_path` = `docs/OSS_INVENTORY.md` und
  `oss_inventory_verify_entrypoint` = `python scripts/verify_oss_inventory_version_truth.py --check`.
- **proprietary-service:** diese beiden Felder **weglassen** (Vorhandensein ⇒ `blocked`).

### 2.3 `proprietary_verification` (nur prop + hybrid)

- `verification_authority` — wer attestiert (z. B. „Provider QA (owner)" oder „Auditor XY")
- `evidence_ref` — **nicht-sensible** Referenz (Attestierungs-ID, Report-URL). **Niemals** Token,
  Passwörter, API-Keys, Connection-Strings → sonst HTTP 422.
- `attestation_mode` — `owner-attested` oder `third-party-attested`

### 2.4 `compatibility`, `lifecycle`, `verify_metadata`

- `compatibility.mode` ∈ `exact-only` / `major-compatible` / `additive-minor-compatible`
  (Default `additive-minor-compatible`).
- `compatibility.deprecation_window` — kanonischer Default `one published minor line`
  (abweichende Werte sind erlaubt, erzeugen aber eine **Warnung** → `ready-with-followups`).
- `lifecycle.status` ∈ `draft` / `active-limited` / `active` / `deprecated` / `sunset` / `retired` / `blocked`.
  Neue Boosts starten als `draft` oder `active-limited`, nie als `active` allein wegen vorhandener Docs.
- `verify_metadata.readiness_surface_refs` — deine eigenen Readiness-Endpoints. **Hinweis:** Fabric-seitig
  ist kanonisch nur `GET /health` live (`/api/v1/readiness` existiert nicht → 404).

---

## 3. Vorbereitungs-Runbook (extern, so einfach wie möglich)

1. **Mode wählen** (Abschnitt 1) und die passende Variante aus der Companion-`*.template.json` kopieren
   — dieses innere Objekt ist bereits der komplette, gültige Request-Body.
2. **Identität setzen:** `id`, `tool_key`, `name`, eine kanonische `capability_class`, `runtime_kind`,
   `version`, `release_channel`. (OSS/hybrid: `repository`.)
3. **Docs verlinken:** `docs_entrypoint` auf deine Übersicht (Repo-Pfad bei OSS/hybrid, URL bei prop).
   OSS/hybrid zusätzlich die beiden OSS-Felder exakt wie vorgegeben.
4. **Evidence-Klasse füllen:**
   - OSS: OSS-Inventar + fail-closed Verify-Skript im Repo bereitstellen.
   - prop/hybrid: `proprietary_verification` mit **nicht-sensibler** `evidence_ref`.
5. **Contracts deklarieren:** was du **konsumierst** (mind. `docs-standard` + `admission-governance`;
   prüfe zusätzlich `matrix`, `identity/contracts/surface-admission`, ggf. `combinations/profiles`) und
   was du **produzierst** (`contract_family`, `surface_ref`, `version`).
6. **Compatibility & Lifecycle:** Modus + Deprecation-Window (Default nehmen = keine Warnung),
   Status `draft`, `effective_from` = heute.
7. **Verify-Pfad:** ausführbarer Verify-Entrypoint, Readiness-Refs, `live_verification_target`.
8. **Surfaces & Beispiele beilegen:** Health, Readiness, Version, OpenAPI/Referenz, Webhooks/Events,
   UI/MCP falls vorhanden, Auth-Modus je Surface — plus **mind. 2 Beispiel-Payloads** bei API/Event/Webhook.
9. **Self-Check:** Body gegen `/api/v1/tools/admission/dry-run` posten (Abschnitt 4). **Vorher beim
   Fabric-Kontakt einen Self-Check-Token anfordern** (siehe Auth-Hinweis in Abschnitt 4) — ohne Token
   liefert der Endpoint 401, unabhängig davon, ob der Body korrekt ist. Ziel: HTTP 200,
   `admission_status: "ready"`, leere `blocking_findings`.
10. **Einreichen:** den validierten Body + verlinkte Artefakte/Evidence an das Fabric-Review geben.

---

## 4. Verify / Self-Check gegen die Live-API

Endpoint: `POST /api/v1/tools/admission/dry-run` (Fabric Admission-API). Ergebnis-Semantik — **zwei
Fail-Closed-Ebenen**, das ist der wichtigste Punkt:

| Ergebnis | Bedeutung | Handlung |
|---|---|---|
| **200 · `ready`** | wohlgeformt **und** admittierbar, keine blocking_findings | fertig |
| **200 · `ready-with-followups`** | admittierbar, aber Warnungen (z. B. abweichendes Deprecation-Window) | Warnungen abarbeiten |
| **200 · `blocked`** | wohlgeformt, aber **Regel verletzt** — siehe `blocking_findings` | Body korrigieren |
| **422** | **malformed**: Pflichtfeld fehlt, unbekanntes Feld, oder secret-artige `evidence_ref` | Struktur korrigieren |

Kanonische Fabric-Surfaces, die dieser Pack nutzt:
`GET /api/v1/contracts/matrix` · `.../docs-standard` · `.../admission-governance` ·
`GET /api/v1/identity/contracts/surface-admission` · `GET /api/v1/combinations/profiles` ·
`POST /api/v1/tools/admission/dry-run` · `POST /api/v1/contracts/compatibility/check` · `GET /health`.

**Auth-Hinweis (seit 2026-08-09, geändert gegenüber dem Stand vom 15.07.):** Alle Surfaces außer
`GET /health` verlangen jetzt einen Operator-Token — ohne Token liefert **jede** dieser Routen
(auch nicht existierende) einheitlich `401 {"detail":"Operator authentication token required",
"hint":"Provide X-API-Key, X-Fabric-Auth-Token, or Authorization: Bearer <token> for guarded access"}`.
Das 401 ist also kein Validierungsfehler am Body — es bedeutet nur „kein/kein gültiger Token". Für den
externen Self-Check braucht ein Partner vorab einen von Fabric ausgestellten Token; ohne Koordination
mit dem Fabric-Kontakt ist Schritt 9 des Runbooks nicht selbst durchführbar.

---

## 5. Corner Cases (fail-closed, live bestätigt)

| Situation | Ergebnis | Merke |
|---|---|---|
| `integration_model` fehlt/`null` | **422** | immer setzen |
| Unbekanntes/zusätzliches Feld (jede Ebene) | **422** | `additionalProperties:false` überall |
| `evidence_ref` enthält Token/Passwort/Key/Connection-String | **422** | nur nicht-sensible Referenzen |
| `proprietary-service` **mit** OSS-Feld | **200 · blocked** | prop-Body enthält **keine** OSS-Felder |
| `proprietary-service`/`hybrid` **ohne** `proprietary_verification` | **200 · blocked** | Evidence-Klasse zwingend |
| OSS-Body **ohne** OSS-Felder | **200 · blocked** | OSS braucht Inventar + Verify-Skript |
| `capability_class` nicht kanonisch/fehlt | blockiert | exakt eine der 14 Klassen |
| Self-Check ohne gültigen Operator-Token | **401** auf jeder Route (auch nicht-existenten) | kein Body-Fehler; Token vorher beim Fabric-Kontakt anfordern |
| `contract_family`-Name weicht von der Matrix ab | Drift/blockiert | gegen `GET /api/v1/contracts/matrix` prüfen |
| Nicht-kanonisches `deprecation_window` | **200 · ready-with-followups** (Warnung) | Default `one published minor line` nehmen |
| `readiness_surface_refs` zeigt auf `/api/v1/readiness` (Fabric) | existiert nicht (404) | Fabric-seitig nur `/health`; sonst **eigene** Readiness-URL |
| Docs vorhanden, aber Runtime nicht bewiesen | nicht `active` | Status `draft`/`active-limited`, bis Verify grün |
| Manifest ⇄ Docs ⇄ Live-Surfaces widersprüchlich | Drift = blockierend | eine Wahrheit, keine Shadow-Truth |

---

## 6. Update & Upgrade — beide Richtungen

Governance-Grundlage: `contracts/policies/compatibility_policy.json` (v1.0.0) und
`contracts/policies/deprecation_policy.json` (v1.0.0).

### 6.1 Boost-Update (deine Version ändert sich)

Erlaubte Change-Kinds: `initial-registration`, `patch`, `additive-minor`, `breaking-change`.

- **patch / additive-minor** → **gleiche Major-Linie**. `additive-minor` muss die **Minor** erhöhen
  (nicht auf der alten Minor bleiben). Consumer-`accepted_versions` entsprechend erweitern.
- **breaking-change** → **neue Major** ist Pflicht, bevor der Boost als kompatibel gilt.
  Deprecation-Window für die alte Major veröffentlichen.
- **Jede** Version, die Surfaces/Contracts berührt, geht **erneut durch den Dry-Run** (Abschnitt 4).
  Ziel bleibt `ready`.
- **Lifecycle-Transitionen** (fail-closed):
  - `active → deprecated`: nur mit veröffentlichtem Deprecation-Window.
  - `deprecated → sunset`: nur mit gesetztem `sunset_not_before`.
  - `sunset/blocked → retired`: nur mit vorheriger Sunset-Strecke **oder** dokumentiertem `blocked_reason`.
- Producer/Consumer-Deklarationen bei jeder Version aktuell halten; `surface_ref`/`version` müssen dem
  realen Verhalten entsprechen (sonst Drift).

### 6.2 Fabric-Upgrade (die Plattform ändert sich unter dir)

- **Erkennen:** vor jedem Re-Submit die kanonischen Surfaces konsumieren und mit deinen Deklarationen
  vergleichen — `GET /api/v1/contracts/docs-standard` (→ `standard_version`),
  `GET /api/v1/contracts/matrix` (Family-/Surface-Namen), `GET /api/v1/contracts/admission-governance`
  (Admission-Regeln). Für Kompatibilität einzelner Änderungen: `POST /api/v1/contracts/compatibility/check`.
- **Reagieren:**
  - Steigt `docs_standard_version`, passe `docs_metadata.docs_standard_version` und deine
    `accepted_versions` an; Docs-Pflichtabschnitte gegen den neuen Standard prüfen.
  - Ändert sich die Capability-Class-Liste oder die Matrix, `manifest_document.capability_class` bzw.
    Producer/Consumer-Families nachziehen.
  - Neue **Pflichtfelder** im Admission-Schema (wie zuletzt `integration_model` / `proprietary_verification`
    via #1277) ⇒ Body ergänzen und neu dry-runnen.
- **Kompatibilitätsversprechen der Plattform:** nicht-brechende Fabric-Änderungen bleiben in derselben
  Major-Linie; brechende erfordern eine neue Major mit Deprecation-Window (Default „one published minor
  line"). Ein Boost sollte den Default-Compatibility-Modus `additive-minor-compatible` nutzen, sofern
  kein strengerer nötig ist.
- **Regel:** Fabric bleibt Truth-Owner. Ein Boost ersetzt Matrix-, Docs-Standard- oder Lifecycle-Wahrheit
  **nie** durch lokale Definitionen; er passt sich an oder meldet Drift.

---

## 7. Ownership & Grenzen

- Fabric ist Producer der Admission-Regeln, des Docs-Standards, des Compatibility-Vokabulars und der
  Review-Semantik — und bleibt Admission-/Verdict-Owner.
- Der Boost ist Producer seines Manifests/Provider-Profils, seiner Docs, seines Verify-Pfads und seiner
  Runtime-Evidence.
- Keine Shadow-Truth: kein paralleles Taxonomie-/Lifecycle-Set im Boost.
- Ein vollständiger Pack **garantiert keine Admission**, wenn Runtime oder Security-Posture die
  Live-Verifikation nicht besteht.

---

## 8. Referenzen

- Schema: `contracts/admission/admission_dry_run_input.schema.json` (dual-mode via #1277)
- Governance: `contracts/admission/future_tool_admission_governance.json`
- Docs-Standard: `contracts/docs/docs_standard.json` (v1.0.0)
- Compatibility: `contracts/policies/compatibility_policy.json` (v1.2.0, 14 Capability-Classes)
- Deprecation: `contracts/policies/deprecation_policy.json` (v1.0.0)
- Lifecycle: `contracts/lifecycle/contract_lifecycle_statuses.json`
- Template: `templates/admission/helpifyr_boost_admission_dry_run.template.json`
- Related issues: `#185`, `#192`, `#222`

## License
- License: AGPLv3
- Project: https://helpifyr.com