Service for the Yemaya Study & Deconstruction Workspace (checklist YSD-1003;
architecture:
docs/adr/ADR-0074-yemaya-study-deconstruction-workspace-architecture.md).
Current surface is operational only — health, readiness, metrics, request identity/tracing, structured logging, graceful shutdown, fail-fast configuration. Business routes land with their checklist items (walking skeleton YSD-1030 onward); there are intentionally no placeholder API routes.
Run locally#
pnpm --filter @yemaya/svc-study-workspace serve # tsx watch on :4020
curl -s localhost:4020/health | jq
curl -s localhost:4020/ready | jq # postgres probe activates when DATABASE_URL is set
curl -s localhost:4020/metrics | head
Verify#
npx vitest run --config apps/yemaya/svc-study-workspace/vitest.config.ts
npx tsc --noEmit -p apps/yemaya/svc-study-workspace/tsconfig.app.json
Configuration#
See src/config.ts — zod-validated environment with production consistency
rules (DATABASE_URL required, JSON logs enforced, shutdown grace capped under
the ECS stopTimeout). Deployment contract: deploy/README.md.
Migrations (YSD-3008)#
Forward-only SQL files in migrations/, applied in filename order by
src/persistence/migrate.ts:
- Forward-only with checksums. Each applied file is recorded in
study_schema_migrationswith a sha256; editing an applied file is a hardMigrationDriftError. Fixes ship as NEW files, never edits. - Rollback / forward-fix instructions live in each migration's header
comment (what to
DROPto back out, or why the migration is forward-only). Write the header before the DDL — a migration without one fails review. - Zero/low-downtime discipline. Every migration transaction runs under
lock_timeout(default 5s): a rollout that queues behind a held lock aborts fail-fast — unrecorded and retryable — instead of blocking every later reader/writer while it waits. Prefer additive DDL (IF NOT EXISTS, new tables/columns/indexes); large-table index builds and rewrites need their own plan. Verified bysrc/persistence/migrations-rollout.integration.spec.ts: fresh-vs-stepwise schema equivalence, fail-fast under a held lock, and a live writer running through a rollout with a bounded worst-case write stall — all on scratch databases created and dropped by the suite.
Seed data#
pnpm --dir apps/yemaya/svc-study-workspace exec tsx scripts/seed-dev-data.ts [database-url]
Loads one deterministic, contract-valid study project (fixed UUIDs, tenant
tenant-dev-seed): two works — one broadly granted, one with an expired grant
so every rights-denial surface is explorable — editions, a link-only
stream-reference asset (no media bytes are fabricated), tracks, a scene/shot
hierarchy, anchors, observations, a claim, a creator statement, and a typed
contrast link. Idempotent by check-then-skip (the schema forbids DELETE by
trigger). Media playback needs a real ingest through the UI/API; the seed
deliberately stores no bytes. E2E stack bootstrap (migrations + MinIO bucket + a
synthesized rights-cleared film) stays scripts/e2e-bootstrap.ts.