feat(signage-ai): provider and job models (PPT-2741)

[camreeves]

Part of the AI signage feature (PPT-2741). This is the bottom of the stack: everything else waits on it.

What this adds

Two models and the migration behind them.

SignageAIProvider holds a vendor configuration: which vendor, which model, the endpoint and region, whether it is enabled, which one is the default, and the per-user and per-domain quotas. Credentials are encrypted at rest and never come back out over the API. A provider can be scoped to a single domain or left global.

SignageAIJob is one generation or edit request and the images it produced. It carries the prompt, the state, the candidates, and enough accounting to answer "has this user run out" without a second table.

Notes for review

shard.yml is deliberately untouched so the version bump automation can pick the increment from the commit types. These are feat and fix, so it should land on 9.109.0.

Quota accounting counts failed jobs. That is intentional: a failed job still costs a vendor call, and not counting them turns a retry loop into a free pass. Claiming an image into the media library does not add to usage, since the job that produced it already did.

One thing worth a second opinion: the two enum columns are stored as TEXT with a CHECK constraint rather than a native Postgres ENUM. Every other PGEnumConverter column in this repo (17 of them) uses CREATE TYPE. TEXT plus CHECK is easier to extend later, but it is a third mechanism in a repo that had two, and I would rather that be a decision than an accident. Happy to convert it.

Retention (added after review feedback)

Steve asked for automatic cleanup of old job rows, so there is now a before_create callback that prunes past a retention window as each new job arrives.

It ships off. Nothing happens unless SIGNAGE_AI_CLEANUP_DAYS is set to a positive number of days, so an upgrade never starts deleting a site's history, and somewhere that generates seasonally keeps last year's work by doing nothing. Zero and negatives both read as "keep everything".

Two things in there worth a reviewer's attention.

The delete runs in a nested transaction, which PgORM issues as a SAVEPOINT. before_create runs inside the transaction that inserts the new row, so without it a failed cleanup would abort that insert and a user would fail to generate an image because housekeeping went wrong. A plain rescue does not help, since Postgres has already marked the transaction aborted.

It reads the ids and then deletes them, rather than the single statement this obviously wants to be:

DELETE FROM signage_ai_jobs WHERE id IN (
  SELECT id FROM signage_ai_jobs WHERE created_at < $1
  ORDER BY created_at LIMIT $2 FOR UPDATE SKIP LOCKED)

That does not reliably delete at most n rows. When the planner picks a nested loop semi join it re-runs the subquery once per candidate row, and because SKIP LOCKED and the rows already deleted by the statement change what comes back each time, the delete lands on the union of those evaluations. Confirmed with an audit trigger and auto_explain: a hash semi join runs the Limit once and removes 2 of 3, a nested loop runs it three times and removes all 3. The plan choice moves with table statistics, so it passes in psql and in tests until it does not.

Tested end to end against a local stack with the variable unset, at 90 days and at 30 days, plus the model specs and the 223 rest-api signage controller specs.

One caveat for operators turning it on: the usage report and the per domain monthly quota both read this table, so a window shorter than a month makes both under-count.

Merge order

This one first, and it needs to be tagged before rest-api can pin it. Then rest-api, then backoffice. ts-client, user-interfaces and placeos-docs have no ordering constraint.

Testing

Specs for both models, including the quota arithmetic and the guard against a job with no images array.

[stakach]

LGTM