Corvidae

Corvidae is an internal Bun workspace for agent runtimes, durable workflows, and Svelte interfaces. Turborepo coordinates local quality checks and application builds. The libraries are private, consume one another through workspace:* (Bun's protocol for linking another local workspace), and export TypeScript source directly.

Working locally

Use the Bun version declared in package.json. Install from the root:

bun install --frozen-lockfile
bun run validate

The local quality commands are bun run lint, bun run typecheck, bun run test, bun run build, and bun run format:check. bun run audit checks high-severity dependency advisories through scripts/check-audit-exceptions.ts. The only tolerated advisories are the entries in scripts/audit-exceptions.ts; each needs an owner decision, a tracking issue, a review-by date, and the exact dependency chains that may reach the package. The guard fails when an advisory stops reporting, when the package becomes reachable any other way, or when the review-by date passes, so never add a bare --ignore to the audit command. The internal workspace has no release or deployment pipeline and installs no Git hooks. The tooling that transforms source for the public repositories lives in the separate private stevekinney/corvidae-mirror repository, not here.

Weft's PostgreSQL integration tests start and dispose local clusters. Install PostgreSQL and make initdb and pg_ctl available on PATH before running the complete repository test suite. Those tests use temporary loopback-only databases and require no external credentials.

Run one workspace through its package scripts:

bunx turbo run lint typecheck test --filter=@lostgradient/operative
bun run --filter=@lostgradient/playground dev
bun run --filter=@lostgradient/playground build

Run the cross-component browser suite with bun run test:browser, or use bun run test:browser:preview to exercise production compilation. Run the operator suite with bun run --filter=@lostgradient/interborough test:browser. Both use Playwright. bun run dev:browser-fixtures starts the Bun fixture host for local inspection.

Workspace boundaries

Browser component libraries live in components/: Cinder, Chat, and Editor. Other libraries live in packages/: the agent runtimes, the Weft execution engine and its operator UI, the key-value storage protocol Weft and its adapters share, and Markdown processing. Verification tooling lives in testing/: the shared test infrastructure and the evaluator that scores completed agent runs against versioned rubrics. No library or component may depend on a testing/ workspace at runtime. Repository configuration lives in internal/, including the @lostgradient/typescript presets. Every workspace uses the @lostgradient/* namespace.

The playground is the application under applications/: bun run --filter=@lostgradient/playground dev starts the component playground, and bun run --filter=@lostgradient/playground build exports it as a static site. The weft package owns its weft and weft-mcp source executables. Interborough, under applications/interborough, serves the Weft operator console and a Bureau on one loopback origin (bun run --filter=@lostgradient/interborough dev), and owns the console's browser tests. Tests spanning Cinder, Chat, and Editor live under scripts/browser-fixtures; they need a real browser page, but have no application or package identity. Those hosts compile Svelte and serve their assets with Bun. No workspace uses Vite.

Every source library exposes exactly one package entry:

{
  "name": "@lostgradient/example",
  "private": true,
  "type": "module",
  "exports": { ".": "./src/index.ts" }
}

Import supported values and types from the package root. There are no built library artifacts or public subpath aliases. The consuming application compiles its libraries. Root style imports accompany the interface library APIs so applications receive their required CSS cascade.

Declare a dependency in the workspace that imports it. Internal dependencies use workspace:*; shared third-party versions use the root Bun catalog. Run bun install after changing manifests and commit the resulting root lockfile with the manifests.

Configuration and verification

Environment configuration uses @lostgradient/environmentalist with Zod schemas owned by the workspace that consumes the values. Keep schemas and synchronous resolver functions in environment-configuration.ts beside the relevant runtime or tooling. Import the resolver where the value is needed; call-time settings must remain call-time settings, and importing a library must not require credentials.

Resolution uses explicitly selected environment values and schema defaults only. Pass sources: ['env', 'defaults'], argv: [], and coerce: false; encode existing conversions in schema transforms and omit undefined source entries. Bun and SvelteKit retain responsibility for loading .env files. This does not enable Environmentalist's flag, project-file, or home-directory discovery, and it does not change existing explicit-option precedence or Weft connection-profile resolution. Portable library code uses a custom synchronous source with explicitly mapped canonical keys and no values when Bun and Node globals are absent.

Keep existing environment-variable names and empty-value behavior. Mark credentials with Environmentalist's secret metadata. Chat-room reads private request configuration through its server-only module; browser components continue to receive only their existing explicitly injected configuration. Test setup, environment restoration, child-process inheritance, and bundler replacement keys may use the raw environment, but configuration decisions belong in the owning resolver. bun run test:self enforces that boundary.

Formatting, lint policy, editor settings, dependency versions, and task coordination live at the root. Executable repository tooling lives in the owning workspace's scripts/ directory. Oxlint caps classic cyclomatic complexity—the number of independent paths through a function—at 100 in implementation and tests, and 300 under scripts/; file length remains review guidance.

Compiler options live in the configuration-only @lostgradient/typescript workspace at internal/typescript. It exports library.json and browser.json; both compose the private base.json. Component workspaces extend @lostgradient/typescript/browser.json, which supplies DOM types and browser/Svelte resolution conditions without ambient Bun or Node types. Their tsconfig.browser.json checks production source; tsconfig.json also checks colocated tests and Bun tooling and supports Oxlint's automatic project discovery. Both checks run through typecheck. Root lint rules reject Node/Bun globals and imports in component source, including Svelte scripts. Tests and scripts retain their runtime APIs. Other local TypeScript configurations select their own source files; tool-required application and test configurations remain beside their owners.

Turbo hashes upstream library source through transit tasks—dependency-only tasks that affect cache keys without running a build. Changing a provider therefore invalidates its consumers' checks without building the libraries. Root tool configuration and shared scripts also participate in cache keys.

The root browser fixtures and Weft UI's browser host share buildBrowser and the Svelte compiler from @lostgradient/testing, while each host owns its own server and routes. Chat-room checks generate and cache their SvelteKit configuration and types. Root browser fixture tests generate and cache a manifest plus the explicit list of fixture modules they can load lazily; no upstream library build is required.

bun run test:self checks the workspace architecture, including source exports, dependency cycles, declared imports, catalog use, cache invalidation, build ownership, and the absence of publishing and hook installation. These checks keep the consolidation rules executable.

The migration inventory records source revisions, package mappings, dependency edges, removal decisions, and validation evidence. It is the completion record for this consolidation.

The Operative and Bureau API contract explains typed agents, durable execution, and started-work control. Hierarchical hook composition covers how Bureau, agent and direct-run hooks compose into one immutable plan per run, who can narrow whom, and what a run will tell you about its own plan. Multi-agent lifecycle and communication covers child runs across Operative and Bureau: addressing, observation, typed parent-child signals, delegation budgets, cancellation, recovery, session forking, and the supervisor-mediated communication model. Memory governance and lifecycle evaluation covers governed memory across Memory, Bureau, and Evaluation: authority, admission, recall, retention, legal hold, deletion receipts, what deletion cannot guarantee, and the memory-lifecycle evaluation command. The workflow versioning guide describes version stamps and recovery behavior. Generated codebase reports are disposable; scripts/measure-codebase.ts and scripts/inventory-dependencies.ts write fresh measurements to /tmp by default.

The runtime contracts guide connects provider capabilities, model selection, steering, cleanup, and parent-child communication across packages. Weft's workflow revision guide, shared-store ownership guide, and remote task recovery guide cover durable execution across deployments. For interfaces, start with Cinder composition.

The completed-project documentation audit maps all 28 completed Linear projects to their reader-facing guides and references.