Skip to content

Anuva Python Server API Implementation Log

Created: 2026-05-21 13:30 UTC

Started: 2026-05-21 13:30 UTC

Completed: 2026-05-21 14:15 UTC

Follow-up fix: 2026-05-21 16:40 UTC

Tasks Completed

  • Replaced the old /api/render-jobs surface with /api/worker/v1 job, upload, completion, failure, cancellation, and heartbeat routes.
  • Added shared render-worker auth, request parsing, package assembly, progress conversion, status transition, and S3 signing helpers under src/lib/render-worker/**.
  • Expanded video_generation_jobs with worker-facing status and metadata fields.
  • Added render_workers and render_worker_reports collections and regenerated Payload types.
  • Updated render-job creation and Anuva render artifact URLs to target the new worker API.
  • Added focused worker API integration tests and updated the fake Payload harness to support the new collections and conditional update behavior.
  • Updated core/state docs and .env.example to reflect the implemented worker API.
  • Added a Payload migration that creates render_workers, render_worker_reports, and the matching payload_locked_documents_rels relation columns required by Payload admin locking.
flowchart LR
  schema["Schema + helpers"] --> routes["/api/worker/v1 routes"]
  routes --> package["RenderJobPackage + asset signing"]
  package --> upload["Signed upload + confirm + complete"]
  upload --> docs["Docs parity + tests"]

Files Changed

Code

  • src/collections/anuvax/index.ts
  • src/lib/render-worker/**
  • src/app/api/worker/v1/**
  • src/app/(frontend)/app/presentation/actions.ts
  • src/lib/anuva/orchestration-service.ts
  • src/env.d.ts
  • src/payload-types.ts
  • src/migrations/20260521_164056_add_render_worker_schema.ts
  • src/migrations/index.ts
  • removed src/app/api/render-jobs/**

Tests

  • tests/integration/render-worker-api.integration.test.ts
  • tests/integration/helpers/fake-payload.ts
  • tests/integration/helpers/presentation-fixtures.ts

Docs

  • docs/core/SystemArchitecture.md
  • docs/core/WorkersAndJobs.md
  • docs/core/PresentationConfig.md
  • docs/state/RouteMap.md
  • docs/state/CollectionMap.md
  • docs/state/CurrentImplementationMap.md
  • docs/state/KnownGaps.md
  • docs/state/EnvAndServices.md
  • .env.example
  • docs/changes/2026-05-21-1330-anuva-python-server-api/ImplementationPlan.md

Tests And Commands Run

  • pnpm generate:types
  • pnpm generate:importmap
  • pnpm typecheck
  • pnpm exec vitest run tests/integration/render-worker-api.integration.test.ts tests/integration/presentation-scene-edit-preview.integration.test.ts
  • pnpm exec biome check src/lib/render-worker src/app/api/worker/v1 src/collections/anuvax/index.ts src/lib/anuva/orchestration-service.ts src/app/(frontend)/app/presentation/actions.ts tests/integration/render-worker-api.integration.test.ts tests/integration/helpers/fake-payload.ts tests/integration/helpers/presentation-fixtures.ts docs/core/SystemArchitecture.md docs/core/WorkersAndJobs.md docs/core/PresentationConfig.md docs/state/RouteMap.md docs/state/CollectionMap.md docs/state/CurrentImplementationMap.md docs/state/KnownGaps.md docs/state/EnvAndServices.md docs/changes/2026-05-21-1330-anuva-python-server-api/ImplementationPlan.md
  • pnpm payload generate:db-schema
  • pnpm exec biome check src/migrations/20260521_164056_add_render_worker_schema.ts src/migrations/index.ts docs/state/EnvAndServices.md docs/state/KnownGaps.md docs/changes/2026-05-21-1330-anuva-python-server-api/ImplementationLog.md
  • pnpm typecheck
  • pnpm payload migrate

Decisions Made During Implementation

  • RenderJobPackage.config is the persisted PresentationConfigPublic snapshot with no wrapper.
  • video_generation_jobs.progress remains 0..100 in storage and is translated to 0.0..1.0 at the API boundary.
  • Worker asset download URLs and final render upload URLs are generated on demand from the configured S3-compatible bucket prefixes.
  • Upload confirmation creates or resolves the final media_assets record before the explicit completion step updates the presentation.

Deviations From Plan

  • render_workers was implemented as a global collection with optional workspace context instead of a required workspace-scoped collection. Idle heartbeats do not always carry enough information to assign a workspace safely, so workspace linkage is only stored when the worker has an active job.
  • The S3 presigner is loaded at runtime from the installed pnpm dependency graph instead of a direct top-level dependency because the package was present transitively but not exposed as a direct import in this workspace.

Known Gaps Or Follow-Ups

  • The runtime S3 presigner loader should be revisited if the repo’s package topology changes or if the project adopts a different package manager layout.
  • Signed asset URL generation assumes the current S3 path-style bucket prefixes for media_assets and voiceover_audio_assets; this should be validated against production storage behavior.
  • The new render-worker schema migration is authored and registered, but it still needs to be applied to the active database. In this environment pnpm payload migrate reaches Payload's safety prompt because the database has prior dev-push state, so the admin fix is not live until that migration is explicitly confirmed and run.