openvibers/openvibe.contracts Commits
ADR-015: OpenVibe.AI owns workflows, runs, providers and quotas; products own publication and human review
Changes
nnew file mode 100644@@@ -0,0 +1,61 @@++# ADR-015: AI workflow and publication ownership boundary++++**Status:** Accepted 2026-09-23. OpenVibe.AI deployed the same day (loopback, port 4700); Live's switch++`AI_SERVICE=remote` moves its AI calls onto it.++++## Context and current evidence++++Live held the whole AI subsystem: provider calls (`server/ai/llm.js`, OpenAI-compatible and Anthropic), vision,++whisper transcription, chat AI, AI viewers, moments, slogans, overviews, recaps and translation. Its prompts,++models and spend limits lived in Live's `site_settings`. Network's generated footer copy called a Live internal++endpoint. The publication products built in Waves 16-19 (Wiki, Blog, News, Reviews, Deals, Coupons, Trade) each++need AI drafts. None of them may publish machine output as fact.++++## Decision++++- **OpenVibe.AI owns the machinery:**++ - the provider, model and route registry, with fallbacks and a circuit breaker;++ - versioned prompt templates and workflow definitions, with input and output schemas;++ - runs, request metadata (hashes, not raw prompts, unless debug is enabled explicitly), citations and the++ cache (private, service or public, never crossing actor scope);++ - quotas and usage per caller, and an audit log.++- **Products own publication.** A workflow returns a draft or evidence package with citations and explicit++ gaps. It never writes into a product. The product stores the draft with `ai` or `ai_assisted` authorship.++ The draft stays `noindex` and is never published as fact until a person reviews it. This is enforced by the++ products and openvibe-publishing, not by AI.++- **No fabrication.** A failed or empty source is an explicit state. Workflows have no field that invents++ ratings, prices, dates or authors. Reviews has no rating output, and a Deals price stays null unless a++ source states it.++- **Fallbacks are recorded.** When the primary provider is degraded, AI falls back and records that on the++ run. The stub provider never serves production callers.++- **Callers use service tokens** with `ai.run.create` / `ai.run.read`. Each workflow belongs to a namespace++ (`live.*`, `wiki.*`, …), and callers are limited to theirs.++- **Streamer-specific keys and local transcription stay in Live** until a per-tenant key model exists.++++## Alternatives considered++++- Keeping AI inside Live, with products calling Live: rejected, because every product would depend on the++ streaming app.++- An AI service that also publishes: rejected, because publication truth and review belong to the owning++ product.++++## Migration consequences++++- Live runs its AI features as workflows when `AI_SERVICE=remote`. With the flag unset, nothing changes.++- The Network footer copy moves to `network.site_copy`. Until Network calls AI directly, Live's endpoint++ forwards to it.++- Live's `translations` table cannot be imported, because it lacks the source text. It is recorded as a hold.++++## Rollback++++Unset `AI_SERVICE` in `live.env` and restart Live, which puts it back on its in-process providers. Stopping++OpenVibe.AI touches no product data.++++## Acceptance tests++++- Every workflow has versioned input and output schemas and produces citations or explicit gaps.++- A degraded primary provider falls back, and the run records that.++- A private cache entry never crosses actors.++- A quota is refused before any provider call.++- Products keep AI output as noindex drafts until a person reviews them. Wiki, Blog, News, Reviews, Deals,++ Coupons and Trade each have tests for this.@@@ -18,6 +18,7 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each| [ADR-012](ADR-012-economic-classification.md) | Billing vs loyalty, credits and currency classification | Accepted 2026-09-22; gates Waves 8-10 || [ADR-013](ADR-013-mod-manifest.md) | Mod manifest, trust and sandbox/resource model | Accepted 2026-09-23; gates Waves 12 and 21C || [ADR-014](ADR-014-developer-projects.md) | Developer project, tenant and quota model | Accepted 2026-09-23; gates Waves 20-21 |++| [ADR-015](ADR-015-ai-workflows.md) | AI workflow and publication ownership boundary | Accepted 2026-09-23; OpenVibe.AI deployed || [ADR-016](ADR-016-active-client-updates.md) | Active client update safety and mixed-version window | Accepted 2026-09-23; Track R || [ADR-017](ADR-017-sources-home.md) | Home of the source registry and ingestion runtime | Accepted 2026-09-23: OpenVibe.Sources || [ADR-018](ADR-018-search-home.md) | Home of the search index and query contract | Accepted 2026-09-23: OpenVibe.Search, FTS first |@@@ -29,4 +30,3 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each| [ADR-024](ADR-024-theme-authority.md) | Theme authority between Network and Shared | Accepted 2026-09-23 || [ADR-025](ADR-025-marketplace-scope.md) | Marketplace and commerce scope | Accepted 2026-09-23: Trade stays informational |--ADR-015 (AI workflow and publication ownership) is written with the Wave 13 extraction.
new file mode 100644
new file mode 100644
@@ -0,0 +1,61 @@
@@ -0,0 +1,61 @@
+# ADR-015: AI workflow and publication ownership boundary
+
+**Status:** Accepted 2026-09-23. OpenVibe.AI deployed the same day (loopback, port 4700); Live's switch
+`AI_SERVICE=remote` moves its AI calls onto it.
+
+## Context and current evidence
+
+Live held the whole AI subsystem: provider calls (`server/ai/llm.js`, OpenAI-compatible and Anthropic), vision,
+whisper transcription, chat AI, AI viewers, moments, slogans, overviews, recaps and translation. Its prompts,
+models and spend limits lived in Live's `site_settings`. Network's generated footer copy called a Live internal
+endpoint. The publication products built in Waves 16-19 (Wiki, Blog, News, Reviews, Deals, Coupons, Trade) each
+need AI drafts. None of them may publish machine output as fact.
+
+## Decision
+
+- **OpenVibe.AI owns the machinery:**
+ - the provider, model and route registry, with fallbacks and a circuit breaker;
+ - versioned prompt templates and workflow definitions, with input and output schemas;
+ - runs, request metadata (hashes, not raw prompts, unless debug is enabled explicitly), citations and the
+ cache (private, service or public, never crossing actor scope);
+ - quotas and usage per caller, and an audit log.
+- **Products own publication.** A workflow returns a draft or evidence package with citations and explicit
+ gaps. It never writes into a product. The product stores the draft with `ai` or `ai_assisted` authorship.
+ The draft stays `noindex` and is never published as fact until a person reviews it. This is enforced by the
+ products and openvibe-publishing, not by AI.
+- **No fabrication.** A failed or empty source is an explicit state. Workflows have no field that invents
+ ratings, prices, dates or authors. Reviews has no rating output, and a Deals price stays null unless a
+ source states it.
+- **Fallbacks are recorded.** When the primary provider is degraded, AI falls back and records that on the
+ run. The stub provider never serves production callers.
+- **Callers use service tokens** with `ai.run.create` / `ai.run.read`. Each workflow belongs to a namespace
+ (`live.*`, `wiki.*`, …), and callers are limited to theirs.
+- **Streamer-specific keys and local transcription stay in Live** until a per-tenant key model exists.
+
+## Alternatives considered
+
+- Keeping AI inside Live, with products calling Live: rejected, because every product would depend on the
+ streaming app.
+- An AI service that also publishes: rejected, because publication truth and review belong to the owning
+ product.
+
+## Migration consequences
+
+- Live runs its AI features as workflows when `AI_SERVICE=remote`. With the flag unset, nothing changes.
+- The Network footer copy moves to `network.site_copy`. Until Network calls AI directly, Live's endpoint
+ forwards to it.
+- Live's `translations` table cannot be imported, because it lacks the source text. It is recorded as a hold.
+
+## Rollback
+
+Unset `AI_SERVICE` in `live.env` and restart Live, which puts it back on its in-process providers. Stopping
+OpenVibe.AI touches no product data.
+
+## Acceptance tests
+
+- Every workflow has versioned input and output schemas and produces citations or explicit gaps.
+- A degraded primary provider falls back, and the run records that.
+- A private cache entry never crosses actors.
+- A quota is refused before any provider call.
+- Products keep AI output as noindex drafts until a person reviews them. Wiki, Blog, News, Reviews, Deals,
+ Coupons and Trade each have tests for this.
@@ -18,6 +18,7 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each
@@ -18,6 +18,7 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each
| [ADR-012](ADR-012-economic-classification.md) | Billing vs loyalty, credits and currency classification | Accepted 2026-09-22; gates Waves 8-10 |
| [ADR-012](ADR-012-economic-classification.md) | Billing vs loyalty, credits and currency classification | Accepted 2026-09-22; gates Waves 8-10 |
| [ADR-013](ADR-013-mod-manifest.md) | Mod manifest, trust and sandbox/resource model | Accepted 2026-09-23; gates Waves 12 and 21C |
| [ADR-013](ADR-013-mod-manifest.md) | Mod manifest, trust and sandbox/resource model | Accepted 2026-09-23; gates Waves 12 and 21C |
| [ADR-014](ADR-014-developer-projects.md) | Developer project, tenant and quota model | Accepted 2026-09-23; gates Waves 20-21 |
| [ADR-014](ADR-014-developer-projects.md) | Developer project, tenant and quota model | Accepted 2026-09-23; gates Waves 20-21 |
+| [ADR-015](ADR-015-ai-workflows.md) | AI workflow and publication ownership boundary | Accepted 2026-09-23; OpenVibe.AI deployed |
| [ADR-016](ADR-016-active-client-updates.md) | Active client update safety and mixed-version window | Accepted 2026-09-23; Track R |
| [ADR-016](ADR-016-active-client-updates.md) | Active client update safety and mixed-version window | Accepted 2026-09-23; Track R |
| [ADR-017](ADR-017-sources-home.md) | Home of the source registry and ingestion runtime | Accepted 2026-09-23: OpenVibe.Sources |
| [ADR-017](ADR-017-sources-home.md) | Home of the source registry and ingestion runtime | Accepted 2026-09-23: OpenVibe.Sources |
| [ADR-018](ADR-018-search-home.md) | Home of the search index and query contract | Accepted 2026-09-23: OpenVibe.Search, FTS first |
| [ADR-018](ADR-018-search-home.md) | Home of the search index and query contract | Accepted 2026-09-23: OpenVibe.Search, FTS first |
@@ -29,4 +30,3 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each
@@ -29,4 +30,3 @@ Platform-wide decisions from the OpenVibe development roadmap (section 10). Each
| [ADR-024](ADR-024-theme-authority.md) | Theme authority between Network and Shared | Accepted 2026-09-23 |
| [ADR-024](ADR-024-theme-authority.md) | Theme authority between Network and Shared | Accepted 2026-09-23 |
| [ADR-025](ADR-025-marketplace-scope.md) | Marketplace and commerce scope | Accepted 2026-09-23: Trade stays informational |
| [ADR-025](ADR-025-marketplace-scope.md) | Marketplace and commerce scope | Accepted 2026-09-23: Trade stays informational |
-ADR-015 (AI workflow and publication ownership) is written with the Wave 13 extraction.