Files
canina/backend/src/orchestration-worker/editorial-bridge.md
T

5.0 KiB

Bounded PMO editorial proposal bridge

No live configuration, deployment, publication or execution is introduced. Opt-in transport/startup flag remains unchanged. Core services/controllers are untouched.

Parent contract

POST /internal/prepare-worker/editorial-proposals (plus the application's existing /api global prefix when present), Bearer service credential. Strict JSON body, all fields required, no extra fields:

{
  "requestId": "a client-generated UUID retained across retries",
  "pilotKind": "editorial-research-to-brief-v1",
  "operationMode": "PREPARE",
  "environment": "staging",
  "scope": "EDITORIAL_RESEARCH_TO_BRIEF",
  "researchTopic": "Evidence-based senior dog nutrition research",
  "acceptanceCriteria": ["Cite primary sources with dates", "Return a research brief; do not publish"],
  "commitSha": "40 lowercase hexadecimal characters",
  "budgetLimitCents": 20
}

Topic 1..180 characters, criteria 1..10 items each 1..500 characters; whitespace-only rejected. commitSha must be a string. requestId must be a UUID. Fixed pilot/scope/environment/mode/budget are checked, not caller-controlled options. Department is server-owned CONTENT. Human research topic and criteria are owner-reviewable proposal data, not instructions executed by this endpoint.

201 returns {taskId,key,pilotKind,state,version,department,operationMode,budgetLimitCents,metadata:{scope,acceptanceCriteria,environment,commitSha}}. First success is GATE1_PENDING; replay returns current state, does not undo owner decisions or requeue work. Scope includes pilot kind, topic and explicit no-publication/release/production restriction. key is editorial-v1: plus SHA256 of JSON [authenticatedWorkerId,requestId]. Same request UUID + differing immutable proposal is 409. Concurrent identical requests produce one task, one PREPARE_PROPOSED event, one PREPARE_TRANSITION event. Crash after create can resume DRAFT submission. No arbitrary reads or mutations are exposed.

Explicit grant and author authority

Only canonical server identity pmo, authenticated by a configured unique digest grant with role WORKFLOW_WORKER and included in workerIds, can submit. There was no canonical PMO grant mapping in repository transport configuration: the operator must explicitly provision this grant through the existing fixed /run/secrets/prepare_worker_grants configuration, using a new random dedicated credential, without runtime defaults. Never copy an arbitrary agent/request actor ID or reuse CI identity. Missing pmo grant denies; other valid workers and Stage CI get 403. Transport disabled remains denied/unregistered according to existing registration boundary. No secrets were read or provisioned by this change.

Existing core create/transition APIs accept only Admin/SUPER_ADMIN. This bounded adapter delegates author-only Admin capability, binding id to the authenticated pmo grant, for exactly create PREPARE and DRAFT→GATE1_PENDING. It never uses SUPER_ADMIN, calls decide, approves, queues READY, writes through Prisma, creates outbox/runs, reserves/reconciles costs or submits evidence. Prisma reads only support idempotency/payload reconciliation. Core remains authoritative for kill switch, immutable metadata/events, versioning and independent Gate1 reviewer. No approval bypass or arbitrary Admin endpoint is exposed.

Owner uses existing Backend owner Gate1 queue and independent authenticated SUPER_ADMIN review. This bridge does not replace that UI/API. Current deterministic/Tech transports are not editorial executors: editorial keys are explicitly refused by generic claim/complete even after independent approval. Actual research execution/completion needs a separately reviewed executor/ingestion contract; no toy QA, fake zero cost, release or publication is claimed.

Verification

Disposable PostgreSQL16 (no published ports/live volumes), Node22 private copied dependencies from readonly orchestration-v4-runtime donor, regenerated private Prisma client and real listening Nest TCP HTTP boundary. Evidence directory /opt/services/canina/validation/v4-editorial-bridge/:

  • red.log: missing endpoint 404 vs required 201.
  • tracer-red.log: approved editorial mistakenly admitted by generic tracer (201 vs required 403), fixed with transport fence.
  • green.log: five bridge tests pass, including race/replay/crash recovery, immutable payload conflict, grant/body/scope/production denial, kill switch and independent approval with tracer refusal.
  • regression-final.log / build.log: all 4 worker suites, 46 tests pass (exit 0); full backend tsc -b exits 0. New bridge files scoped ESLint exits 0 (lint.log). Initial combined regression hit a shared fixture kill-switch uniqueness collision; tests now preserve and restore the fixture row.

Tests use disposable fixture commit hashes, not deployed commit evidence. No AppModule, production, live DB, release authorization, push or deploy changes. Parent owns ingress service-network/TLS/body/rate limits and reviewed grant provisioning. This commit is the proposal slice only.