Skip to content

local-development.md

Latest commit

 

History

History
90 lines (57 loc) · 5.39 KB

local-development.md

File metadata and controls

90 lines (57 loc) · 5.39 KB
Raw

Local Development

Prerequisites

  • Node.js >=22.12; CI uses Node 22.14.0.
  • Corepack and pnpm 10.30.1.
  • PostgreSQL 16 only when running integration tests.

Bootstrap the workspace from the repository root:

corepack enable
pnpm install
pnpm test
pnpm typecheck

The lockfile is authoritative. CI uses pnpm install --frozen-lockfile; use the same command when checking a clean install.

Local State

The shared packages do not impose a global state directory. Composition chooses explicit locations for:

  • a local LocalArtifactStore root, which holds content-addressed payloads, traces, artifacts, and snapshots;
  • PostgreSQL, when durable journal, command/outbox, projection, harness, workflow, or ambient state is required;
  • optional fixture output and logs.

Keep development state outside tracked fixture paths, for example under ./.tracer-evolve/, and do not commit it. A filesystem artifact root is safe only for one host or a shared durable filesystem with atomic rename semantics. Do not point multiple independent hosts at unrelated local artifact roots.

Database Integration

The PostgreSQL integration suite is intentionally skipped when TEST_DATABASE_URL is absent. Start a disposable database and set a URL, then run:

export TEST_DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/tracer_evolve_test
pnpm test:integration

The integration test applies packages/storage/src/migrations/001_initial.sql to a fresh database. The migration is an initial schema, not a repeatable reset script. Drop and recreate the disposable database before reapplying it locally.

For a manually composed control plane, use a separate runtime DATABASE_URL and apply the same migration once before starting workers. Do not share the test database with a development process.

Development Commands

The Task 12 composition exposes the following root commands:

pnpm dev
pnpm agent run --fixture examples/coding-agent/task.json
pnpm agent evolve --goal-family coding-fixture
pnpm agent run --fixture examples/coding-agent/task.json
pnpm agent replay <successful-run-id>

dev executes the deterministic fixture once. run persists every execution under the returned runId. replay rebuilds that exact run from recorded events and effect outcomes; it does not re-contact a model or tool. evolve starts an evidence-backed candidate round for a goal family and publishes only after validation and the trusted release gate accept it.

The CLI includes a deterministic local composition for the checked-in fixture and retains a composition seam for production services. Local state defaults to .tracer-evolve/<repository-name>/state.json; set TRACER_EVOLVE_STATE_DIR to isolate runs. The local fixture is a behavioral proof, not a production replacement for PostgreSQL, durable artifact storage, workers, or external model/tool providers.

Local Control-Plane Workflow

  1. Compose createControlPlane with durable stores and runtime operators, then start its Fastify server.
  2. Send authenticated ambient events to POST /v1/ambient/events; the authenticated principal must be allowed to assert the supplied source.
  3. Inspect or answer/cancel/replay Goals through the authenticated operator routes.
  4. Inspect Trial and verifier evidence before asking evolution to validate a candidate.
  5. Grant approvals through the operator boundary only when the policy requires them.
  6. Promote or roll back a Harness channel through the release authority, never by editing a manifest or database row.

Ambient acceptance writes the source/delivery dedupe record, ambient.received event, and wake intent together. Wakes use a leased, retry-bounded outbox. A crash after acceptance is recovered by a dispatcher claiming the pending or expired wake intent with the same event id as its downstream idempotency key.

Troubleshooting

TEST_DATABASE_URL is missing

This is expected for unit-only development. The integration suite is reported as skipped. Set TEST_DATABASE_URL only for a disposable PostgreSQL database and rerun pnpm test:integration.

pnpm cannot install native build dependencies

The workspace allows the esbuild install build in pnpm-workspace.yaml. On a fresh machine, let pnpm process the configured approval or run pnpm approve-builds only after reviewing the package list. Do not bypass the lockfile or add broad build approvals to make an install succeed.

FileProvider or managed-filesystem errors

Some desktop/managed folders expose files through a provider that does not support the rename, file-lock, or executable semantics pnpm and the filesystem CAS need. Move the working tree and local artifact root to a normal local volume, clear only the affected local store, then reinstall with the pinned lockfile. Do not use a cloud-synced directory as the shared artifact store.

A replay differs from the original run

Treat this as an integrity defect. Confirm that the same event journal, Harness snapshot, Workflow version, verifier definitions, and recorded effect results are present. Replay must not silently fall back to live model/tool calls.

A wake remains pending or retries repeatedly

Inspect ambient_wake_intents, the delivery event, and worker logs. Confirm the worker can claim leases and that its wake handler accepts the event id as an idempotency key. Do not manually mark a wake succeeded; recover it through the dispatcher or explicitly record a terminal failure.