feat: add standalone constructive-infra pgpm package

.agents/skills/compute-worker/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: compute-worker
+description: Platform-aware compute worker and service for constructive-functions. Discovers functions from the database, tracks invocations, dispatches via HTTP. Use when working on the compute-worker, compute-service, function discovery, or invocation tracking.
+---
+
+# Compute Worker & Service
+
+The compute-worker is a platform-aware replacement for the legacy knative-job-worker. Instead of discovering functions from a static manifest or env vars, it queries `constructive_infra_public.platform_function_definitions` and tracks every invocation in `platform_function_invocations`.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ compute-service (orchestrator)                          │
+│                                                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
+│  │ HTTP callback │  │ ComputeWorker│  │  Scheduler   │  │
+│  │ server (:8080)│  │ (polls jobs) │  │ (cron jobs)  │  │
+│  └──────────────┘  └──────┬───────┘  └──────────────┘  │
+│                           │                              │
+│            ┌──────────────┼──────────────┐               │
+│            │              │              │               │
+│            ▼              ▼              ▼               │
+│    FunctionDiscovery  InvocationTracker  compute_request │
+│    (TTL-cached DB     (INSERT/UPDATE    (HTTP POST to   │
+│     lookups)          invocations)      function URL)   │
+└─────────────────────────────────────────────────────────┘
+         │                    │                │
+         ▼                    ▼                ▼
+  platform_function    platform_function    Function HTTP
+  _definitions         _invocations        endpoint
+  (read)               (write)             (send-email:8081)
+```
+
+## Packages
+
+### job/compute-worker (`@constructive-io/compute-worker`)
+
+Core worker class and supporting modules:
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | `ComputeWorker` class — lifecycle, job polling, dispatch |
+| `src/discovery.ts` | `FunctionDiscovery` — lazy TTL-cached DB lookups |
+| `src/invocation.ts` | `InvocationTracker` — create/complete/fail invocation records |
+| `src/req.ts` | `compute_request()` — HTTP POST dispatch with X-* headers |
+| `src/cache.ts` | `TtlCache<T>` — generic TTL cache |
+| `src/types.ts` | TypeScript interfaces |
+
+### job/compute-service (`@constructive-io/compute-service`)
+
+Orchestrator that starts the callback server, ComputeWorker, and Scheduler:
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | `ComputeService` class + `bootCompute()` entry point |
+| `src/run.ts` | CLI entry point (`node dist/run.js`) |
+| `src/registry.ts` | Function registry loader (for optional in-process function servers) |
+| `src/types.ts` | TypeScript interfaces |
+
+## Key differences from legacy worker
+
+| Feature | knative-job-worker | compute-worker |
+|---------|-------------------|----------------|
+| Function discovery | Static manifest / `JOBS_SUPPORTED` env | DB query (TTL-cached) |
+| Invocation tracking | None | `platform_function_invocations` table |
+| Task filtering | `JOBS_SUPPORTED` allowlist | Accepts any registered task |
+| URL resolution | Gateway URL + dev map | `service_url` from DB → dev map → gateway fallback |
+| Infra requirement | Only needs `app_jobs` schema | Needs `app_jobs` + `constructive_infra_public` |
+
+## Function discovery flow
+
+```
+Job arrives (task_identifier = "send-email")
+  │
+  ▼
+FunctionDiscovery.resolve("send-email")
+  │
+  ├─ Cache hit? → return cached definition
+  │
+  └─ Cache miss? → SQL query:
+       SELECT * FROM constructive_infra_public.platform_function_definitions
+       WHERE task_identifier = 'send-email'
+       │
+       └─ Cache result (TTL default: 60s)
+          │
+          ▼
+     PlatformFunctionDefinition {
+       id, name, task_identifier, service_url,
+       is_invocable, max_attempts, priority, ...
+     }
+```
+
+## Invocation lifecycle
+
+```
+1. create() → INSERT INTO platform_function_invocations
+              (status='running', started_at=now())
+              → returns invocation_id
+
+2a. complete() → UPDATE SET status='completed',
+                 completed_at=now(), duration_ms=X
+
+2b. fail()     → UPDATE SET status='failed',
+                 completed_at=now(), duration_ms=X, error='...'
+```
+
+## Running locally
+
+```bash
+# Tier 1: pgpm-local
+pgpm docker start --image docker.io/constructiveio/postgres-plus:18
+eval "$(pgpm env)"
+make setup-platform    # deploy infra + seed functions
+make dev-compute       # start compute-service + functions
+
+# Tier 2: compose-local
+make dev               # docker compose up
+make dev-compute       # start compute-service + functions
+```
+
+## Testing a job manually
+
+```bash
+# Insert a test job
+eval "$(pgpm env)"
+psql -d constructive-functions-db1 -c "
+  INSERT INTO app_jobs.jobs (task_identifier, payload)
+  VALUES ('send-email', '{\"to\":\"test@example.com\",\"subject\":\"test\",\"html\":\"<p>hi</p>\"}'::json)
+"
+
+# Check invocation records
+psql -d constructive-functions-db1 -c "
+  SELECT id, task_identifier, status, duration_ms, error
+  FROM constructive_infra_public.platform_function_invocations
+  ORDER BY started_at DESC LIMIT 5
+"
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COMPUTE_JOBS_ENABLED` | `true` | Enable/disable the compute worker |
+| `COMPUTE_CALLBACK_URL` | — | URL functions POST to on completion |
+| `COMPUTE_GATEWAY_URL` | — | Fallback gateway URL for functions without `service_url` |
+| `JOBS_SCHEMA` | `app_jobs` | PostgreSQL schema for the jobs table |
+| `INTERNAL_JOBS_CALLBACK_PORT` | `8080` | Port for the HTTP callback server |
+| `INTERNAL_GATEWAY_DEVELOPMENT_MAP` | — | JSON map of task→URL for local dev |
+
+## Database requirements
+
+The compute-service checks two things at boot:
+1. `app_jobs.jobs` table exists (deployed by `@pgpm/database-jobs`, a dependency of `constructive-infra`)
+2. `constructive_infra_public.platform_function_definitions` table exists (deployed by `constructive-infra`)
+
+Both are deployed together via `make setup-platform` or the `platform-setup` Docker Compose service.

.agents/skills/dev-tiers/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: dev-tiers
+description: Three-tier local development environment for constructive-functions. Covers pgpm-local (Tier 1), compose-local (Tier 2), and k8s-local (Tier 3). Use when setting up the dev environment, starting services, or debugging infrastructure.
+---
+
+# Development Tiers
+
+constructive-functions supports three tiers of local development, each adding more infrastructure while keeping the same function code. Choose based on what you need.
+
+## Tier 1 — pgpm-local
+
+**What it is:** Postgres only via `pgpm docker`. Functions + services run as bare Node.js processes on the host. Fastest edit-run cycle.
+
+**When to use:** Day-to-day function development, quick iteration, debugging a single function.
+
+**Setup:**
+```bash
+# Start Postgres
+pgpm docker start --image docker.io/constructiveio/postgres-plus:18
+eval "$(pgpm env)"
+
+# Deploy infra schema + seed function definitions
+make setup-platform
+
+# Generate function packages (if not done)
+pnpm generate && pnpm install && pnpm build
+
+# Start functions + compute-service (platform-aware)
+make dev-compute
+
+# Or start functions + legacy job-service
+make dev-fn
+```
+
+**What runs where:**
+| Component | Where |
+|-----------|-------|
+| PostgreSQL | Docker container (via pgpm) |
+| MinIO (optional) | Docker container (via pgpm) |
+| Functions (send-email, etc.) | Local Node.js process |
+| compute-service / job-service | Local Node.js process |
+| GraphQL server | Not running (unless started manually) |
+
+**Database:** `constructive-functions-db1` (configurable via `DB_NAME` env var)
+
+**Ports:**
+| Service | Port |
+|---------|------|
+| PostgreSQL | 5432 |
+| compute-service / job-service | 8080 |
+| send-email | 8081 |
+| send-verification-link | 8082 |
+
+---
+
+## Tier 2 — compose-local
+
+**What it is:** Docker Compose runs infrastructure (Postgres, db-setup, GraphQL server, mailpit, platform-setup). Functions still run as local Node.js processes.
+
+**When to use:** Testing with full infrastructure, working with email, needing GraphQL API, integration testing.
+
+**Setup:**
+```bash
+# Create .env from example
+cp .env.example .env
+
+# Start infrastructure
+make dev                     # docker compose up -d
+
+# Wait for db-setup + platform-setup to complete
+docker compose logs -f db-setup platform-setup
+
+# Start functions + compute-service
+make dev-compute
+
+# Or start functions + legacy job-service
+make dev-fn
+```
+
+**What runs where:**
+| Component | Where |
+|-----------|-------|
+| PostgreSQL | Docker container |
+| db-setup (deploys constructive, metaschema) | Docker container (runs once) |
+| platform-setup (deploys constructive-infra, seeds functions) | Docker container (runs once) |
+| GraphQL server | Docker container (port 3002) |
+| Mailpit (email testing) | Docker container (SMTP 1025, UI 8025) |
+| Functions | Local Node.js process |
+| compute-service / job-service | Local Node.js process |
+
+**Database:** `constructive` (full constructive stack)
+
+**Ports:**
+| Service | Port |
+|---------|------|
+| PostgreSQL | 5432 |
+| GraphQL server | 3002 |
+| Mailpit SMTP | 1025 |
+| Mailpit UI | 8025 |
+| compute-service / job-service | 8080 |
+| send-email | 8081 |
+| send-verification-link | 8082 |
+
+---
+
+## Tier 3 — k8s-local
+
+**What it is:** Everything runs in a local Kubernetes cluster via Skaffold. Two sub-profiles: `local-simple` (plain Deployments) and `local` (Knative Serving).
+
+**When to use:** Testing K8s manifests, verifying production-like behavior, testing Knative scaling, pre-deployment validation.
+
+**Setup (local-simple — no Knative):**
+```bash
+# One-time: install K8s tooling
+make setup-dev
+
+# Start everything
+make skaffold-dev
+```
+
+**Setup (local — Knative):**
+```bash
+# One-time: install Knative operators
+cd k8s && make operators-knative-only
+
+# Start everything
+make skaffold-dev-knative
+```
+
+**What runs where:**
+| Component | Where |
+|-----------|-------|
+| Everything | Kubernetes pods |
+
+**Key manifests (local-simple overlay):**
+- `k8s/overlays/local-simple/postgres-local.yaml` — PostgreSQL StatefulSet
+- `k8s/overlays/local-simple/constructive-db-job.yaml` — DB setup Job
+- `k8s/overlays/local-simple/job-service.yaml` — Legacy job service Deployment
+- `k8s/overlays/local-simple/compute-service.yaml` — Platform-aware compute service Deployment
+- `k8s/overlays/local-simple/constructive-server.yaml` — GraphQL server
+
+---
+
+## Switching between tiers
+
+The tiers are independent. Tear down one before starting another to avoid port conflicts:
+
+```bash
+# Stop Tier 2
+make dev-down
+
+# Stop Tier 3
+# Ctrl+C in the skaffold terminal
+
+# Stop Tier 1
+pgpm docker stop
+```
+
+## Environment variables
+
+Common env vars across all tiers:
+
+| Variable | Tier 1 Default | Tier 2 Default | Description |
+|----------|---------------|---------------|-------------|
+| `PGHOST` | localhost | localhost | PostgreSQL host |
+| `PGPORT` | 5432 | 5432 | PostgreSQL port |
+| `PGUSER` | postgres | postgres | PostgreSQL user |
+| `PGPASSWORD` | (from pgpm env) | (from .env) | PostgreSQL password |
+| `PGDATABASE` | constructive-functions-db1 | constructive | Database name |
+| `JOBS_SCHEMA` | app_jobs | app_jobs | Jobs table schema |
+| `COMPUTE_JOBS_ENABLED` | true | true | Enable compute worker |