# Grounded AI, Integrations, and SEO

Phase 13 adds provider-neutral grounded catalog recommendations, a transactional
integration outbox for consent-safe analytics forwarding, and governed public
metadata, sitemap, robots, and local redirect delivery.

## Grounded AI contract

- An AI provider configuration stores a driver, model identifier, lifecycle,
  non-secret configuration, and an encrypted credential envelope. Credentials
  are write-only in the administration UI and excluded from audit payloads.
- An agent selects allowed subject types and a bounded maximum result count.
  Its stable scheduling reference is `ai:<agent-slug>`.
- The orchestrator retrieves at most 20 currently published services/templates,
  sends only public IDs, names, and lock versions to the provider port, and
  validates every returned ID against that exact retrieved set. Duplicate,
  malformed, excessive, and invented results fail closed.
- AI output never contains authoritative prices. Any commercial result must use
  the deterministic pricing engine and an immutable quotation snapshot.
- Run evidence stores a request hash, retrieved IDs/versions, validated structured
  output, provider request reference, safe usage/latency metadata, and a bounded
  failure code. Raw intents, credentials, prompts, and provider error messages
  are not retained. Run rows are immutable.
- The shipped `deterministic` adapter is a local verification adapter. Real
  vendor adapters implement the same `AiProvider` port and must preserve these
  retrieval, validation, privacy, and failure contracts.

## Integration and consent contract

- Analytics acceptance dispatches a minimal domain event inside the same database
  transaction. The synchronous listener appends an outbox message atomically,
  using the analytics event UUID as its unique replay key.
- Outbox payloads contain only the already allow-listed event name, properties,
  source, and occurred time. Raw anonymous/session IDs and PII are never copied.
- Each active connection has an event allow-list and an explicit
  `consent_required` flag. Granted events may reach the provider adapter; denied
  or unknown events are recorded as `skipped` before adapter invocation.
- Dispatch locks one message, writes idempotent per-connection delivery evidence,
  sanitizes failures to exception class/error code, and retries with bounded
  backoff. Content fields on outbox events are immutable.
- `integrations:dispatch-outbox --limit=100` runs every minute with overlap and
  multi-node protection. The shipped `null` transport certifies orchestration
  without network transmission; production provider transports implement the
  `IntegrationTransport` port.

## SEO contract

- Route metadata is unique by route name and resource key. `*` provides a route
  default; a bound public UUID overrides it for one post or job.
- Titles, descriptions, robots directives, canonical local paths, and Open Graph
  fields are escaped through the shared public meta partial. External canonical
  targets, queries, and fragments are rejected.
- `/sitemap.xml` is generated from current public routes, published posts, and
  currently open jobs. A resource-specific or route-default `noindex` override
  removes that URL. The projection is cached for 15 minutes and invalidated on
  metadata changes.
- `/robots.txt` advertises the sitemap and excludes administration/account paths.
- Redirects accept only local source/target paths, only permanent 301/308 status,
  prevent self-targets, and cannot claim security, API, health, authentication,
  sitemap, or robots prefixes. Existing application routes always win before the
  final redirect resolver.

## Access and operations

- `ai.manage`, `integrations.manage`, and `seo.manage` are independent. The
  console, navigation, queries, and mutations render/authorize each section
  separately; `integrations.manage` remains a privileged 2FA permission.
- Keep the scheduler and queue/runtime supervisors healthy, monitor pending or
  terminal outbox volume, skipped-consent rates, adapter failures, AI failure
  codes/latency, and sitemap freshness.
- Run MySQL 8 CI before production certification. SQLite verifies functional and
  rollback behavior but not concurrent `FOR UPDATE` delivery claims.
- Threat-model every new AI or integration adapter before activation. Permit only
  explicitly reviewed outbound hosts, use least-privilege provider credentials,
  define retention, and exercise provider outage/replay recovery.