docs/unified-publishing.md

# Unified Publishing Center

## Architecture

The Publishing Center is a composition layer over `app/social`. It does not
own provider connections, tokens, media files, publishing jobs, retries, or
provider payload translation.

The authoritative flow is:

1. A canonical `SocialPost` references a workspace project and Social media
   asset.
2. Each exact connected account creates one `SocialPostTarget`.
3. `PublishingService` validates account state, authorization scopes, provider
   capabilities, canonical asset ownership, project provenance, and adapter
   media constraints.
4. Publish-now creates idempotent `SocialJob` records. Scheduling creates one
   durable `SocialSchedule` stored in UTC with its IANA display timezone.
5. Existing Social workers claim jobs atomically and call the registered
   provider adapter.
6. Provider results and reconciliation update each target independently.
   Post reconciliation reports `published`, `failed`, or `partial_success`.

Provider adapters remain the only components that translate canonical post
data into provider API payloads. An adapter that is registered but does not
advertise publishing remains unavailable and must raise
`SOCIAL_PROVIDER_NOT_IMPLEMENTED` or `SOCIAL_CAPABILITY_UNSUPPORTED`; neither
condition is converted to success.

## Canonical post and targets

`SocialPost` now records optional immutable project provenance, a bounded
canonical caption, and bounded canonical hashtags. Platform overrides remain
on targets and never mutate the canonical copy.

Target input is strict. YouTube, TikTok, X, and LinkedIn use their existing
typed provider metadata models. Providers without implemented publishing
contracts are capability-gated instead of accepting arbitrary payloads.

No binary media or credentials are stored in Social records. A Social media
asset binds an existing canonical MediaRouter asset to a validated immutable
output locator.

## Validation

`POST /v1/social/posts/{post_id}/validate` returns a structured result for
every target. Validation reuses:

- connected-account and OAuth scope checks;
- provider capability metadata;
- canonical Social media resolution;
- existing FFprobe/media validation;
- each provider adapter's `validate_media` implementation.

The publish and schedule paths revalidate server-side. Frontend validation is
advisory and cannot authorize publishing.

## Scheduling and jobs

Scheduling uses `SocialSchedule`; timestamps must be offset-aware and are
stored as UTC. The supplied IANA timezone is retained for display. The
existing scheduler claims due records using row locks and `SKIP LOCKED`.
Publishing jobs use deterministic per-target idempotency keys and bounded
worker concurrency.

Provider-native scheduling is used only by an adapter when explicitly
supported. The Publishing Center otherwise relies on MediaRouter's durable
scheduler. The separate Calendar interface is outside this phase.

## Retries, reconciliation, and partial success

The existing worker retry classifier applies exponential backoff and jitter
to transient errors. Invalid credentials, invalid media, permission denial,
unsupported operations, cancellation, and non-retryable provider responses
are not retried indefinitely. OAuth 401 handling refreshes once through
`OAuthService`.

The Publishing Center also exposes a target-scoped retry endpoint. It only
accepts a failed target with no external provider ID, rejects permanent
configuration/auth/media failures, and derives a deterministic retry job key.
It never requeues successful or uncertain provider operations.

Async provider acceptance is reconciled through the adapter's status or
recovery contract. MediaRouter does not claim exactly-once external delivery
where the provider cannot support lookup or idempotency; local idempotency
prevents duplicate internal operations.

Targets reconcile independently. A mixture of published and failed targets
produces `partial_success`, never `published`.

## Cancellation

Draft, scheduled, queued, and retrying jobs can transition to `cancelled`.
Preparing, processing, uploading, and publishing jobs instead record
`cancellation_requested_at`. Their target remains in its actual state until
the worker/provider result is reconciled. This prevents MediaRouter from
claiming cancellation after a provider may have accepted a post.

## Security, permissions, and RLS

The API uses existing Social scopes:

- `social:accounts:read` / `social:accounts:write`
- `social:posts:read` / `social:posts:write`
- `social:posts:publish`
- `social:schedules:write`

Project and asset ownership is checked server-side. The additive migration
adds a project foreign key, a same-workspace integrity trigger, indexes, and
retains forced RLS on posts, targets, and jobs. Social accounts, media
references, targets, schedules, and jobs continue using the existing
workspace policies. Runtime PostgreSQL RLS certification remains deferred.

Tokens are available only through `TokenService`. REST, SDK, MCP, n8n, logs,
audits, and job payloads never expose access tokens, refresh tokens, provider
secrets, authorization headers, or signed upload/session URLs.

## Audit and retention

The Publishing Center uses existing bounded Social audit records, including
post creation, validation, scheduling, publish start, completion/failure, and
cancellation. Audit and application logs contain opaque resource identifiers,
provider, status, duration, and error categories only.

Raw provider payloads are not retained by the composer. Provider recovery
state that must survive restarts remains encrypted in the existing dedicated
job field. Public result metadata is filtered before transport.

## Frontend

Routes:

- `/publish`
- `/projects/[projectId]/publish`

TanStack Query owns providers, accounts, assets, posts, jobs, and validation
responses. The composer keeps only draft selections in local UI state. It
requires exact account selection, capability-gates unavailable adapters,
registers an existing project output as a Social media reference when needed,
and requires an accessible confirmation dialog before external publishing.
Status uses the existing Social job polling rather than a second realtime
system.

Project actions link to the project-aware route. Content Studio, AI Studio,
and template-created projects use the same project/asset provenance and
publishing APIs; there is no specialized publishing path.

## Copilot

The shared Copilot action registry contains:

- `publishing.validate`
- `publishing.create_post`
- `publishing.schedule`
- `publishing.publish`
- `publishing.cancel`

Publish, schedule, and cancellation are registered as external side effects
and always require confirmation. Copilot uses exact post/account identifiers
and the canonical Social services; it cannot invoke an adapter or arbitrary
function directly.

## SDK, MCP, and n8n

TypeScript and Python SDKs extend the existing Social resource with structured
validation and the new canonical fields. Existing methods remain compatible.

MCP exposes typed validation and job listing alongside existing create,
publish, schedule, cancel, and status tools. Authorization remains enforced by
the MCP registry.

The existing n8n Social node adds List Posts, Validate Post, and List
Publishing Jobs. Operations use the official SDK, preserve idempotency and
Continue On Fail, and return real per-target backend state.

## Provider certification boundary

Unit tests may mock provider boundaries. Live provider certification, live
OAuth credentials, Docker, PostgreSQL runtime/RLS verification, FFmpeg runtime
verification, and final production hardening remain deferred. An
`implementation_status` of `registered` or a false publishing capability is
shown as unavailable and is never simulated.