docs/publishing-operations-phase9.md

# Publishing Operations — Phase 9

## Status

Publishing operations are implemented in the current working tree with durable
unified jobs, calendar/queue/draft flows, retries, idempotency, and SDK/MCP/n8n
transport coverage. PostgreSQL/RLS runtime verification, Docker, FFmpeg,
Hugging Face startup, live provider certification, and final production
certification remain deferred until all planned product phases are complete.

## Audit

The Phase 8 audit found one authoritative publishing domain under
`app/social/`. `SocialPost` is already the canonical draft/post record, a
post owns multiple `SocialPostTarget` rows, `SocialSchedule` stores UTC
timestamps plus the requested IANA timezone, and `SocialJob` is the durable
per-target queue consumed by the existing scheduler and publisher workers.
Provider adapters, OAuth/TokenService, capability discovery, asset ownership,
RLS, retries, cancellation requests, reconciliation, partial success, SDK,
MCP, n8n, Copilot, project provenance, and Content Studio integration are
reused. No duplicate post, account, asset, or job tables were introduced.

Phase 9 adds revision-safe draft mutation and rescheduling, queue/calendar
read models, and durable bounded bulk orchestration. `revision` on posts and
schedules is additive and is checked server-side for updates, duplication, and
rescheduling. `social_publishing_batches` and
`social_publishing_batch_items` are additive, workspace-isolated orchestration
records; individual posts/jobs retain their own state and idempotency.

## State and APIs

Existing `/v1/social/posts`, `/publish`, `/schedule`, `/cancel`, validation,
jobs, accounts, and provider routes remain canonical. Phase 9 adds:

- `GET /v1/social/drafts`
- `PATCH/DELETE /v1/social/drafts/{post_id}`
- `PATCH /v1/social/posts/{post_id}`
- `POST /v1/social/posts/{post_id}/duplicate`
- `POST /v1/social/posts/{post_id}/reschedule`
- `GET /v1/social/publishing-context`
- `GET /v1/social/calendar`
- `GET /v1/social/queue`
- `POST /v1/social/bulk`

The batch operation is `schedule`, `reschedule`, `cancel`, `duplicate`, or
`delete`. Batch items are claimed with `FOR UPDATE SKIP LOCKED` by the existing
Social scheduler boundary and report independent completion/failure.

Drafts remain `draft` until server validation. `validating` and `ready` are
reserved state vocabulary for future asynchronous validation materialization;
provider execution continues to use the existing `queued` → `preparing` →
`processing` → `uploading` → `publishing` → terminal transitions. No frontend
can arbitrarily mutate execution state.

## Calendar and timezone model

The calendar accepts an aware UTC range and returns scheduled posts with the
stored schedule timezone and schedule revision. Workspace timezone is read
from authoritative workspace metadata, defaulting to UTC only when no
workspace timezone has been configured. UI date-time inputs are explicitly
labelled with that timezone and converted to an instant before mutation.
Invalid, past, unordered, or excessively broad ranges are rejected.

## Queue and bulk behavior

Queue filtering supports provider, account, project, status, search, bounded
pagination, and live polling through TanStack Query. Bulk requests are
bounded to 100 posts, idempotent at batch level, and never clone provider job
IDs or provider references. Batch processing runs through the existing worker
loop; partial item failure produces `partial_success` at the batch level.

## Security, permissions, RLS, and audit

Existing Social scopes are reused: `social:posts:read/write/publish`,
`social:schedules:read/write`, and account scopes. The BFF continues to enforce
same-origin and session permission checks before forwarding authenticated
requests. Migration `0009_publishing_operations.sql` enables and forces RLS
for batch tables, adds workspace checks, foreign keys, indexes, and revision
columns without destructive changes. Audit events use bounded
`publishing.*` names alongside legacy Social event names; credentials, signed
URLs, provider payloads, and binary media are never recorded.

## Integrations

The Composer, Calendar, Queue, and Drafts routes use the existing Workspace
shell, design system, Social hooks, canonical project assets, and provider
capabilities. TypeScript and Python SDK Social resources expose draft,
duplicate, reschedule, calendar, queue, and bulk methods. MCP exposes narrowly
scoped queue/calendar/reschedule/duplicate/bulk tools through the shared
service. The official n8n Social node exposes deterministic queue/calendar,
duplicate, reschedule, and bulk operations through the SDK credential.

## Runtime limitations

Local validation is limited by the available Termux environment. PostgreSQL
RLS runtime checks, Docker, FFmpeg, Hugging Face startup, live provider
credentials, provider certification, production OpenAPI verification, and
final production hardening remain intentionally deferred until all MediaRouter
product phases are complete.