Technische FreigabeArbeitsstand · Nur lokale Ansicht

Controlled Source Pack Write API Decision

Controlled Source Pack Write API Decision

Die Decision ist umgesetzt: Growth OS hat jetzt eine streng begrenzte interne Write-API fuer Draft-Erstellung und Observation-Ergaenzung. PATCH fuer Draft-Felder und Archive wurden spaeter separat begrenzt ergaenzt; DELETE und Candidate-Handoff bleiben blockiert.

Migration / API FoundationPersistence DecisionSource PacksProject Overview
Implementation Foundation - begrenzte Write API

Create Draft und Add Observation sind API-seitig bereit

Die erste Write-Stufe ist auf zwei interne API-Aktionen begrenzt: Source Pack Draft erstellen und Source Observation hinzufuegen. Beide nutzen Boundary Guards, schreiben nur Arbeitsstand und erzeugen keinen Candidate.

  • nur Create Draft
  • nur Add Observation
  • Manual Create UI begrenzt angebunden
  • kein Candidate-Handoff
  • keine Umsatzberechnung

Controlled Source Pack Write API Foundation

Erste Write-Stufe gebaut, Manual Create UI nutzt sie begrenzt

Create Draft und Add Observation speichern nur Source-Pack-Arbeitsstand. Die API gibt sichere Read Models zurueck und erzeugt keinen Candidate.

Create Draft

POST /api/internal/source-packs

  • POST /api/internal/source-packs erstellt nur status=draft.
  • InitialObservations werden optional in derselben Transaktion gespeichert.
  • Response gibt SourcePackReadModel zurueck, keine raw DB Row.
  • created_at und updated_at werden serverseitig gesetzt.

Add Observation

POST /api/internal/source-packs/[id]/observations

  • POST /api/internal/source-packs/[id]/observations fuegt eine Observation zu einem bestehenden Source Pack hinzu.
  • Parent source_packs.updated_at wird serverseitig aktualisiert.
  • Observation Summary bleibt kurze eigene Zusammenfassung.
  • redactionStatus startet ohne Client-Vorgabe mit needs_review.

Boundary Guard

Validate-Only-Regeln bleiben Pflicht

  • Forbidden Keys blockieren vor jedem Write.
  • Riskante Claims werden als blockedClaims sichtbar oder blockieren den Write.
  • Warnings bleiben in der Response sichtbar.
  • Validate-Only bleibt unveraendert nicht-schreibend.

Manual Create UI

Nur begrenzte Draft-Speicherung

Die Source-Pack-UI darf Drafts speichern und Observations ergaenzen. Full Edit, Delete und Handoff bleiben blockiert.

No Candidate Handoff

Kein Source-Pack-zu-Candidate-Flow

Ein Source Pack bleibt Arbeitsstand und erzeugt keinen Offer-Radar-Candidate.

Current Write Scope

Begrenzte Writes fuer Draft, Observation und Archive

  • create draft source pack
  • add source observation to source pack
  • update source pack draft fields
  • archive source pack by status
  • read/list bleibt ueber bestehende Read API
  • validate-only bleibt Gate vor jedem echten Write

Later Scope

Observation Edit, Restore und Handoff spaeter

  • update source observation
  • restore/unarchive policy
  • Source Pack zu Offer Radar Handoff
  • bulk oder adapter write

Blocked Scope

Kein Delete, kein Handoff, kein Adapter-Write

  • delete source pack
  • bulk import
  • adapter write
  • Source Pack zu Offer Radar Candidate
  • Candidate Handoff
  • Umsatzpotenzial-Berechnung

Create / Update / Archive Boundary

Welche Writes kontrolliert erlaubt sind

Create, Add Observation, begrenztes Draft-Update und Archivieren sind kontrolliert erlaubt. Observation Edit, Restore, Delete und Handoff bleiben eigene Entscheidungen.

first_write_candidate

Create Source Pack Draft

Decision

Als erster Write-Baustein erlaubt, aber nur fuer Draft-Arbeitsstaende mit sichtbaren Evidence Boundaries.

Allowed when

  • Validate-Only liefert keine Errors.
  • blockedClaims und missingEvidence sind sichtbar.
  • revenuePotentialStatus bleibt qualitativ.
  • server setzt id, created_at und updated_at.

Blocked because

  • keine Validierung
  • keine Candidate-Erzeugung
  • keine Launch-Freigabe
  • keine Umsatzannahme

first_write_candidate

Add Source Observation

Decision

Als zweiter Write-Baustein erlaubt, wenn Observation Summary kurz bleibt und Redaction Gate greift.

Allowed when

  • source_pack_id existiert serverseitig.
  • observationSummary ist kurze eigene Zusammenfassung.
  • signalTypes sind bekannte qualitative Signaltypen.
  • redactionStatus ist needs_review, redacted oder blocked.

Blocked because

  • keine Rohdaten-Sammlung
  • keine langen Fremdtexte
  • keine personenbezogenen Community-Daten
  • keine Proof- oder Revenue-Claims

first_write_candidate

Update Source Pack Draft

Decision

Begrenzt umgesetzt: nur erlaubte Source-Pack-Draft-Felder, keine Observation-Editierung.

Allowed when

  • nur erlaubte Felder werden gepatcht
  • updated_at wird serverseitig gesetzt
  • status transition ist erlaubt

Blocked because

  • keine Validierung
  • keine Candidate-Erzeugung
  • keine Observation-Editierung

first_write_candidate

Archive Source Pack

Decision

Begrenzt umgesetzt als nicht-destruktiver Statuswechsel. Delete bleibt blockiert.

Allowed when

  • status transition fuehrt zu archived
  • kein physisches Loeschen

Blocked because

  • keine Datenvernichtung
  • kein Handoff
  • keine Validierung

later

Update Source Observation

Decision

Spaeter nur mit Redaction-Bewusstsein; Observation-Updates duerfen keine Rohdaten nachtraeglich einschleusen.

Allowed when

  • Redaction Status bleibt sichtbar.
  • Summary bleibt kurz.
  • disallowedInferences bleiben erhalten oder werden bewusst ersetzt.

Blocked because

  • Observation ist Evidence Boundary, nicht Freitext-Ablage.
  • Review-/History-Frage ist noch offen.

blocked

Delete, Bulk Import, Adapter Write, Candidate Handoff

Decision

Nicht Teil der ersten Write API.

Allowed when

    Blocked because

    • Delete braucht Retention-/Audit-Entscheidung.
    • Bulk Import kann Rohdaten und AI-Slop einschleusen.
    • Adapter Writes brauchen eigene Rechts- und Quellenentscheidung.
    • Candidate Handoff braucht expliziten separaten Flow.

    Allowed Fields

    Welche Felder in Create und begrenztem Update erlaubt sind

    Erlaubte Felder bleiben Arbeitsmaterial. Systemfelder bleiben serverseitig.

    source_pack

    title

    create: allowedupdate: allowed

    Arbeitstitel, kein Potenzial- oder Validierungslabel.

    source_pack

    workingHypothesis

    create: allowedupdate: allowed

    Hypothese bleibt Arbeitsstand.

    source_pack

    targetAudience

    create: allowedupdate: allowed

    Audience ist Annahme, keine Marktgroesse.

    source_pack

    possibleOfferShape

    create: allowedupdate: allowed

    Formatidee ohne Launch- oder Delivery-Versprechen.

    source_pack

    revenuePotentialStatus

    create: allowedupdate: allowed

    Nur qualitative Boundary-Werte, keine Zahlen.

    source_pack

    evidenceSummary

    create: allowedupdate: allowed

    Kurze Signalzusammenfassung, kein Rohdatenarchiv.

    source_pack

    missingEvidence

    create: allowedupdate: allowed

    Fehlende Evidence muss sichtbar bleiben.

    source_pack

    blockedClaims

    create: allowedupdate: allowed

    Blockiert Proof-, Revenue-, Launch- und Validation-Claims.

    source_pack

    recommendedNextStep

    create: allowedupdate: allowed

    Naechster Pruefpfad, keine Ausfuehrung.

    source_pack

    handoffDraft

    create: allowedupdate: allowed

    Nur Brief. Erzeugt keinen Candidate.

    source_pack

    redactionNotes

    create: allowedupdate: allowed

    Notiz zur Datenqualitaet, keine sensiblen Rohdaten.

    source_observation

    initialObservations

    create: allowedupdate: blocked

    Nur kurze eigene Observations, keine Raw Scrapes.

    system

    id / created_at / updated_at

    create: server_onlyupdate: server_only

    Server setzt technische Felder. Client darf sie nicht bestimmen.

    Forbidden Fields

    Harte Blocklist fuer spaetere Writes

    Diese Felder duerfen auch spaeter nicht in Source-Pack-Write-Payloads akzeptiert werden.

    • id
    • candidate_id
    • offer_radar_candidate_id
    • score
    • scores
    • ranking
    • rankings
    • validation_status
    • validated_at
    • validated
    • launch_approval
    • launch_ready
    • conversion_rate
    • cpc
    • search_volume
    • revenue_estimate
    • revenue_potential_amount
    • created_from_adapter_run
    • external_raw_payload
    • raw_scrape_content
    • raw_source_content

    Status Transitions

    Status ist Arbeitsstand, nicht Freigabe

    Erlaubt sind nur Draft-, Review-, Parked- und Archive-Uebergaenge. Es gibt keinen Status fuer Validierung, Launch oder Empfehlung.

    Allowed Transitions

    Erlaubte Uebergaenge

    • draft -> needs_review: Review-Anfrage, keine Validierung.
    • draft -> parked: Arbeitsstand parken.
    • needs_review -> draft: Zurueck in Bearbeitung.
    • needs_review -> parked: Review nicht entscheidungsreif.
    • parked -> draft: Wieder aufnehmen.
    • any -> archived: Nicht-destruktiv archivieren, nicht loeschen.

    Blocked Status Labels

    Nicht erlaubte Status

    • validated
    • launch_ready
    • approved
    • recommended
    • high_potential

    Redaction Gate

    Observation Writes brauchen Redaction-Grenzen

    Source Observations duerfen nur kurze eigene Signalzusammenfassungen speichern. Rohdaten, personenbezogene Inhalte und lange Fremdtexte bleiben blockiert.

    Redaction Rule

    Default Redaction Status

    Neue Observations starten mit redaction_status = needs_review, wenn kein anderer erlaubter Wert gesetzt ist.

    Write darf speichern, aber UI/API muss Review-Bedarf sichtbar halten.

    Redaction Rule

    Nur kurze eigene Zusammenfassungen

    observationSummary bleibt kurze eigene Zusammenfassung.

    Lange Fremdtexte, Raw Scrapes und Copy-Paste-Sammlungen blockieren den Write.

    Redaction Rule

    Source Reference optional

    sourceReference ist optional und kontrolliert.

    Keine personenbezogenen, geheimen oder lizenzkritischen Referenzen.

    Redaction Rule

    Blocked bleibt speicherbar

    redaction_status = blocked darf gespeichert werden, wenn die Observation als nicht nutzbar markiert werden soll.

    Blocked Observations duerfen keine positiven Inferences staerken.

    Validate-Only to Write Gate

    Validate-Only wird Pflicht-Gate

    Jeder spaetere Write muss denselben Boundary Guard nutzen. Validate-Only bleibt nicht-schreibend und wird nicht zur versteckten Create-Route.

    Hard Rule

    Errors blockieren Writes

    Jeder spaetere Write muss denselben Boundary Guard nutzen wie Validate-Only.

    Wenn Validate-Only Errors liefert, darf der Write nicht speichern.

    Warnings

    Warnings bleiben sichtbar

    Warnings duerfen Draft-Speicherung zunaechst erlauben, muessen aber in Response/UI sichtbar bleiben und blockieren jede Review- oder Handoff-Wirkung.

    • Warnings stillschweigend ignorieren
    • Write ohne blockedClaims
    • Write mit riskanten Claims ohne Boundary
    • Write als Validierung markieren
    • Write als Candidate-Erzeugung interpretieren

    updated_at Rule

    Zeitwerte werden serverseitig gesetzt

    Die DDL hat keinen Auto-Update-Trigger. Spaetere Write-Operationen muessen updated_at bewusst serverseitig setzen.

    source_pack

    updated_at wird serverseitig bei jedem Source-Pack-Write gesetzt.

    Client darf updated_at nicht setzen. Kein DB-Trigger in diesem Block.

    source_observation

    updated_at wird serverseitig bei jedem Observation-Write gesetzt.

    Observation-Zeitpunkt ist technischer Arbeitsstand, keine Evidence-Qualitaet.

    source_pack

    Add Observation aktualisiert spaeter auch source_packs.updated_at.

    Das zeigt Arbeitsstand-Aenderung, nicht Signalstaerke.

    API Error Contract

    Fehler bleiben kontrolliert und nicht-sensitiv

    Spaetere Write Errors muessen klare Boundary Notes liefern, aber keine DB-Details, Secrets oder raw Payloads spiegeln.

    Error Contract

    validation_failed

    Bedeutung

    Payload verletzt Boundary Guards.

    Boundary

    Keine raw Validation Internals oder DB-Details nach aussen.

    Error Contract

    forbidden_payload_key

    Bedeutung

    Payload enthaelt ein hart blockiertes Feld.

    Boundary

    Feld nennen, aber keine internen Stacktraces.

    Error Contract

    blocked_claim

    Bedeutung

    Payload behauptet Validierung, Launch, Umsatz oder Proof.

    Boundary

    Claim-Grenze sichtbar machen.

    Error Contract

    redaction_required

    Bedeutung

    Observation braucht Redaction oder ist als Raw Content riskant.

    Boundary

    Datenschutz-/Quellenrechtsgrenze nennen, keine Rohdaten spiegeln.

    Error Contract

    source_pack_not_found

    Bedeutung

    Ziel-Source-Pack existiert nicht.

    Boundary

    Kein DB-Detail leaken.

    Error Contract

    schema_not_ready

    Bedeutung

    Manuelle Persistenzstruktur ist nicht erwartungsgemaess verfuegbar.

    Boundary

    Keine SQL- oder Secret-Details.

    Error Contract

    database_unavailable

    Bedeutung

    DB ist nicht erreichbar.

    Boundary

    Keine Connection Strings, keine Secrets.

    Error Contract

    internal_error

    Bedeutung

    Unbekannter Serverfehler.

    Boundary

    Knappe Fehlermeldung plus Boundary Note.

    Future Smoke Concept

    Write-Smoke erst bauen, wenn Write existiert

    Dieser Block erweitert noch keinen Write-Smoke. Die spaetere Write-Foundation muss synthetische Payloads nutzen und Cleanup ohne echte Kundendaten klaeren.

    Future Smoke

    Safe create payload

    Synthetischer Draft wird akzeptiert und danach ueber Read Model gelesen.

    Keine echten Kundendaten, kein Candidate.

    Future Smoke

    Forbidden payload

    Score, Ranking, Candidate-ID, Revenue-Estimate und Raw Payload werden geblockt.

    Kontrollierter Error Contract.

    Future Smoke

    Validate-Only bleibt nicht-schreibend

    Count vor/nach Validate-Only bleibt gleich.

    Validate-Only ist kein Write.

    Future Smoke

    updated_at serverseitig

    Read nach Write zeigt serverseitig gesetzten Zeitwert.

    Zeitwert ist Arbeitsstand, kein Proof.

    Future Smoke

    No raw DB rows

    Response enthaelt Read Model und keine snake_case DB-Felder.

    API Contract bleibt Schutzschicht.

    Next Build Block

    Source Pack UI Hardening / Read Model Polish

    Source Pack UI Hardening / Read Model Polish: nach Edit und Archive die Arbeitsflaeche und Read Models schaerfen.

    • Arbeitsflaeche verdichten
    • Read Models polieren
    • weiterhin kein Handoff
    • weiterhin kein Delete