# Project export: lambda-fluid

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: imagine a simplified version vercel's fluid compute architecture but built OSS which you can just drop into your existing infrastructure.
- Devpost: https://devpost.com/software/lambda-fluid
- GitHub: https://github.com/rust-soham/lambda-fluid
- Video: https://www.youtube.com/embed/8OLAnBziIAk?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — Rust-soham (11 commits)

## Devpost submission (written by the team)

### Inspiration

came across Vercel’s Fluid Compute and got curious about how it works under the hood. Lambda Fluid started as an attempt to rebuild the core idea on AWS Lambda.

### What it does

Normally, a Lambda sits around doing very little while its request waits on a database or API. Lambda Fluid lets that same running Lambda work on other requests during the wait. How I built it It’s written in TypeScript with EffectTS. There’s an orchestrator that receives requests, tracks worker health, and routes work to Lambda workers through a persistent tunnel. I also built local and AWS demos so the behavior can be compared. Challenges I ran into TCP framing, concurrent routing, retries, cancellation, and Lambda’s 15-minute lifetime all caused some headaches. The AWS deployment tooling also had a couple of beta-related surprises. Accomplishments that I'm proud of The full pipeline works locally, and the same worker runtime also runs on a real AWS Lambda. The demos show concurrent requests, streaming responses, health-based routing, and fewer Lambda environments. What I learned The main challenge isn’t starting more Lambdas. It’s figuring out how much work an existing Lambda can safely take without overwhelming it.

### What's next

improve the AWS benchmarks, support normal HTTP handlers, make scaling smarter, and package the whole thing so it’s easier to drop into an existing project.

## README (from the GitHub repository)

# Lambda Fluid

Lambda Fluid is an Effect-based reconstruction of the core idea behind fluid
serverless compute: keep a Lambda invocation alive as a worker, send multiple
logical HTTP requests through one outbound tunnel, and let the Node.js event
loop execute another request while earlier requests await I/O.

This is an OSS prototype and developer tool, not a hosted multi-tenant service.
One orchestrator manages one application and one compatible worker pool.

## Quick evaluation

Install and verify:

```bash
pnpm install
pnpm check
pnpm test
```

### Mode 1: completely local

No cloud credentials are needed. These finite commands exercise the client,
HTTP orchestrator, adaptive fleet, TCP tunnels, workers, and streamed responses.

```bash
pnpm bench examples/01-order.ts
pnpm bench examples/02-three-endpoints.ts
```

### Mode 2: local orchestrator to AWS Lambda

This bundles the chosen example handler into an Alchemy-managed Lambda, starts a
temporary public worker ingress, and routes the same 30-request workload through
real Lambda workers.

```bash
pnpm infra:login --profile builder
pnpm demo:local-aws examples/01-order.ts --profile builder
pnpm demo:local-aws examples/02-three-endpoints.ts --profile builder
```

Mode 2 requires `cloudflared`, creates or updates AWS resources, and can incur
charges. Read the setup and cleanup guide before running it.

## Judge and agent guide

Start with the [documentation navigator](docs/README.md). It includes:

- a five-minute evaluation path;
- architecture and request-flow diagrams;
- both supported execution modes;
- a package-by-package source tour;
- protocol, concurrency, routing, and lifecycle explanations;
- benchmark interpretation;
- an explicit implemented-versus-incomplete matrix.

The shortest source-reading path is:

1. [`examples/01-order.ts`](examples/01-order.ts) — ordinary application code.
2. [`packages/orchestrator/src/control-plane.ts`](packages/orchestrator/src/control-plane.ts) — routing and response correlation.
3. [`packages/worker/src/runtime.ts`](packages/worker/src/runtime.ts) — concurrent logical jobs.
4. [`packages/tunnel/src/channel.ts`](packages/tunnel/src/channel.ts) — bidirectional framed transport.
5. [`packages/aws-runtime/src/lambda-handler.ts`](packages/aws-runtime/src/lambda-handler.ts) — Lambda adapter.

## Scope

The supported evaluation surface is deliberately limited to:

1. fully local end-to-end execution;
2. a local orchestrator controlling AWS Lambda workers.

`research/` preserves the reasoning and source research that led here; `docs/`
describes what the checked-in implementation does now.


## Detected evidence (automated analysis)

Indexed codebase: 83 recognized source files, 1009 KB.
- TypeScript (language) — detected in the code
- AI coding agent: Codex — evidence: config files committed to the repository

## Codebase structure (from repository index)

### Files (105 of 105)

```
.agents/transcripts/ig writing a higher level abstraction on top of ku.md
.agents/transcripts/so iam doing a http from tcp course on bootdev in.md
.gitignore
.vscode/extensions.json
.vscode/settings.json
AGENTS.md
docs/01-architecture.md
docs/02-mode-1-local.md
docs/03-mode-2-local-aws.md
docs/04-codebase-tour.md
docs/05-protocol-and-lifecycle.md
docs/06-routing-and-scaling.md
docs/07-benchmarking.md
docs/08-current-status.md
docs/README.md
examples/01-order.ts
examples/02-three-endpoints.ts
package.json
packages/aws-runtime/package.json
packages/aws-runtime/src/direct-worker-invoker.ts
packages/aws-runtime/src/index.ts
packages/aws-runtime/src/invocation.ts
packages/aws-runtime/src/lambda-handler.ts
packages/aws-runtime/src/launcher.ts
packages/aws-runtime/src/worker-invoker.ts
packages/aws-runtime/tsconfig.json
packages/benchmark-cli/package.json
packages/benchmark-cli/src/cli.ts
packages/benchmark-cli/src/load-definition.ts
packages/benchmark-cli/src/report.ts
packages/benchmark-cli/tsconfig.json
packages/benchmark/package.json
packages/benchmark/src/definition.ts
packages/benchmark/src/index.ts
packages/benchmark/src/order-handler.ts
packages/benchmark/src/synthetic-workload.ts
packages/benchmark/tsconfig.json
packages/infra/alchemy.run.ts
packages/infra/aws/lambda-worker.ts
packages/infra/package.json
packages/infra/scripts/alchemy-aws.mjs
packages/infra/scripts/run-example.mjs
packages/infra/smoke.aws.run.ts
packages/infra/smoke/aws-lambda.ts
packages/infra/tsconfig.json
packages/orchestrator/package.json
packages/orchestrator/src/adaptive-capacity.ts
packages/orchestrator/src/control-plane.ts
packages/orchestrator/src/fleet-registry.ts
packages/orchestrator/src/fleet-state.ts
packages/orchestrator/src/http.ts
packages/orchestrator/src/index.ts
packages/orchestrator/src/websocket.ts
packages/orchestrator/src/worker-state.ts
packages/orchestrator/test/adaptive-capacity.test.ts
packages/orchestrator/test/control-plane.test.ts
packages/orchestrator/test/fleet-state.test.ts
packages/orchestrator/test/worker-state.test.ts
packages/orchestrator/tsconfig.json
packages/protocol/package.json
packages/protocol/src/framing.ts
packages/protocol/src/index.ts
packages/protocol/src/schema.ts
packages/protocol/src/schema/base.ts
packages/protocol/src/schema/identifiers.ts
packages/protocol/src/schema/job.ts
packages/protocol/src/schema/response.ts
packages/protocol/src/schema/tunnel.ts
packages/protocol/src/schema/worker.ts
packages/protocol/src/tunnel-codec.ts
packages/protocol/test/framing.test.ts
packages/protocol/tsconfig.json
packages/tunnel/package.json
packages/tunnel/src/channel.ts
packages/tunnel/src/index.ts
packages/tunnel/test/channel.test.ts
packages/tunnel/test/tcp.test.ts
packages/tunnel/tsconfig.json
packages/worker/package.json
packages/worker/src/index.ts
packages/worker/src/job-handler.ts
packages/worker/src/runtime.ts
packages/worker/src/tunnel-session.ts
packages/worker/src/worker-state.ts
packages/worker/test/runtime.test.ts
packages/worker/tsconfig.json
pnpm-workspace.yaml
README.md
research/01-project-charter.md
research/02-runtime-foundations.md
research/03-reference-architecture.md
research/04-protocol-and-data-model.md
research/05-effect-design.md
research/06-billing-and-benchmarking.md
research/07-delivery-roadmap.md
research/08-infrastructure-health.md
research/primary-sources.md
research/README.md
scripts/prepare-effect.sh
src/main.ts
src/modes/demo-local-aws.ts
src/modes/local-aws.ts
src/quick-tunnel.ts
tsconfig.json
vite.config.ts
```

### Dependencies

- package.json: @effect/platform-node@4.0.0-beta.98, @lambda-fluid/aws-runtime@workspace:*, @lambda-fluid/benchmark@workspace:*, @lambda-fluid/benchmark-cli@workspace:*, @lambda-fluid/orchestrator@workspace:*, @lambda-fluid/protocol@workspace:*, @lambda-fluid/worker@workspace:*, @types/node@^25.9.0, @voidzero-dev/vite-plus-core@0.2.5, effect@4.0.0-beta.98, vite@catalog:, vite-plus@catalog:
- packages/aws-runtime/package.json: @distilled.cloud/aws@0.29.1, @effect/platform-node@4.0.0-beta.98, @effect/vitest@4.0.0-beta.98, @lambda-fluid/protocol@workspace:*, @lambda-fluid/worker@workspace:*, @types/node@^25.9.0, effect@4.0.0-beta.98, vitest@catalog:
- packages/benchmark-cli/package.json: @effect/platform-node@4.0.0-beta.98, @lambda-fluid/benchmark@workspace:*, @lambda-fluid/orchestrator@workspace:*, @lambda-fluid/protocol@workspace:*, @lambda-fluid/worker@workspace:*, @types/node@^25.9.0, effect@4.0.0-beta.98, vite@catalog:
- packages/benchmark/package.json: @lambda-fluid/protocol@workspace:*, @lambda-fluid/worker@workspace:*, @types/node@^25.9.0
- packages/infra/package.json: @effect/platform-node@4.0.0-beta.98, @lambda-fluid/aws-runtime@workspace:*, @lambda-fluid/benchmark@workspace:*, @types/node@^25.9.0, alchemy@2.0.0-beta.63, effect@4.0.0-beta.98
- packages/orchestrator/package.json: @effect/platform-node@4.0.0-beta.98, @effect/vitest@4.0.0-beta.98, @lambda-fluid/benchmark@workspace:*, @lambda-fluid/protocol@workspace:*, @lambda-fluid/tunnel@workspace:*, @lambda-fluid/worker@workspace:*, @types/node@^25.9.0, effect@4.0.0-beta.98, vitest@catalog:
- packages/protocol/package.json: @effect/vitest@4.0.0-beta.98, @types/node@^25.9.0, effect@4.0.0-beta.98
- packages/tunnel/package.json: @effect/platform-node@4.0.0-beta.98, @effect/vitest@4.0.0-beta.98, @lambda-fluid/protocol@workspace:*, @types/node@^25.9.0, effect@4.0.0-beta.98, vitest@catalog:
- packages/worker/package.json: @effect/vitest@4.0.0-beta.98, @lambda-fluid/protocol@workspace:*, @lambda-fluid/tunnel@workspace:*, @types/node@^25.9.0, effect@4.0.0-beta.98, vitest@catalog:

### Recent commits (newest first)

- docs: add judge-facing codebase guide
- feat: add local and AWS Lambda Fluid demos
- feat: add worker runtime and TCP tunnel
- feat: add adaptive fleet routing and tunnel protocol
- refactor: scope orchestrator to one worker pool
- feat: adapt worker admission from health
- feat: model worker draining lifecycle
- wip
- chore: migrate tooling to Vite+
- chore: establish project research and workspace
- feat: model worker admission protocol
- init

## Key source files (fetched from GitHub, selected and truncated for size)

### AGENTS.md

```markdown
# Agent orientation

Read `README.md`, then `docs/README.md`. Treat `docs/08-current-status.md` as the
claims boundary: do not describe partially implemented behavior as complete.

## Safe first commands

```bash
pnpm check
pnpm test
pnpm bench examples/01-order.ts
```

The benchmark is finite and local. AWS commands mutate external state and may
cost money; only run them when explicitly requested.

## Architecture invariants

- One orchestrator manages one application worker pool; there is no active
  multi-tenant `deploymentId` model.
- Public clients speak HTTP. Internal request, attempt, worker, and frame fields
  do not cross the client response boundary.
- The orchestrator owns routing estimates and reservations. The worker owns the
  final transactional admission decision and may nack.
- Selection plus reservation must stay atomic through STM.
- Application handlers are ordinary TypeScript functions bundled into workers;
  executable code is never sent over the tunnel.
- Distilled AWS imports belong only in the direct external-host adapter. The
  launcher depends on the project-owned `WorkerInvoker` service.
- Expected failures remain typed Effect values. Do not introduce `any`, unsafe
  casts, or exception-driven application control flow.

## Navigation

- Wire schemas and framing: `packages/protocol`
- Socket Channels: `packages/tunnel`
- Worker concurrency: `packages/worker`
- Fleet and routing: `packages/orchestrator`
- Lambda adapter and invocation capability: `packages/aws-runtime`
- Application examples: `examples`
- Composition roots: `src`
- Alchemy deployment: `packages/infra`

Use package-local source imports such as `effect/Effect`, not aggregate imports
from `effect`. Keep composition roots thin and domain behavior in packages.

```

### research/primary-sources.md

```markdown
# Primary Sources

## Vercel

- [Fluid: How we built serverless servers](https://vercel.com/blog/fluid-how-we-built-serverless-servers)
  - Function Router, compute resolver, Rust core, secure TCP-based protocol,
    streaming, resource metrics, nack, and in-function concurrency.
- [How Fluid compute works on Vercel](https://vercel.com/blog/how-fluid-compute-works-on-vercel)
  - product and routing overview.
- [Serverless servers: Node.js with in-function concurrency](https://vercel.com/blog/serverless-servers-node-js-with-in-function-concurrency)
  - concurrency motivation and Node.js behavior.
- [Introducing Active CPU pricing for Fluid compute](https://vercel.com/blog/introducing-active-cpu-pricing-for-fluid-compute)
  - active CPU pricing terminology.
- [Vercel function usage and pricing](https://vercel.com/docs/functions/usage-and-pricing)
  - active CPU, provisioned memory, and invocation terms.

## AWS Lambda

- [Understanding Lambda function scaling](https://docs.aws.amazon.com/lambda/latest/dg/lambda-concurrency.html)
  - conventional invocation concurrency and execution environments.
- [Lambda runtimes](https://docs.aws.amazon.com/lambda/latest/dg/runtimes-open-source.html)
  - runtime API context.
- [Lambda Managed Instances runtime](https://docs.aws.amazon.com/lambda/latest/dg/lambda-managed-instances-nodejs-runtime.html)
  - AWS's own in-environment concurrency comparison point.

## Project Tooling

- [Effect documentation](https://effect.website/docs/)
- [Effect v4 beta release notes](https://effect.website/blog/releases/effect/40-beta/)
- [Alchemy repository](https://github.com/alchemy-run/alchemy)

The installed Effect and Alchemy package declarations are authoritative for
implementation API shape. The transcript is not.

```

### package.json

```
{
  "name": "lambda-fluid",
  "version": "1.0.0",
  "private": true,
  "description": "",
  "keywords": [],
  "license": "ISC",
  "author": "",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "build": "vp build --ssr src/main.ts",
    "build:bench": "vp build --ssr packages/benchmark-cli/src/cli.ts --outDir packages/benchmark-cli/dist",
    "infra:dev": "vp run @lambda-fluid/infra#dev --",
    "infra:deploy": "vp run @lambda-fluid/infra#deploy --",
    "infra:destroy": "vp run @lambda-fluid/infra#destroy --",
    "infra:login": "vp run @lambda-fluid/infra#login --",
    "infra:profile": "vp run @lambda-fluid/infra#profile --",
    "infra:plan": "vp run @lambda-fluid/infra#plan --",
    "prepare": "./scripts/prepare-effect.sh",
    "check": "vp check",
    "test": "vp test run",
    "format": "vp fmt",
    "format:check": "vp fmt --check",
    "lint": "vp lint",
    "lint:fix": "vp lint --fix",
    "local": "vp build --ssr src/main.ts && node dist/main.js",
    "local:aws": "vp build --ssr src/modes/local-aws.ts --outDir dist/local-aws && vp run @lambda-fluid/infra#local-aws --",
    "demo:local-aws": "vp build --ssr src/modes/demo-local-aws.ts --outDir dist/demo-local-aws && vp run @lambda-fluid/infra#demo-local-aws --",
    "bench": "vp build --ssr packages/benchmark-cli/src/cli.ts --outDir packages/benchmark-cli/dist && node packages/benchmark-cli/dist/cli.js"
  },
  "dependencies": {
    "@effect/platform-node": "4.0.0-beta.98",
    "@lambda-fluid/aws-runtime": "workspace:*",
    "@lambda-fluid/benchmark": "workspace:*",
    "@lambda-fluid/orchestrator": "workspace:*",
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/worker": "workspace:*",
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@lambda-fluid/benchmark-cli": "workspace:*",
    "@types/node": "^25.9.0",
    "@voidzero-dev/vite-plus-core": "0.2.5",
    "vite": "catalog:",
    "vite-plus": "catalog:"
  },
  "packageManager": "pnpm@11.1.0"
}

```

### packages/benchmark/package.json

```
{
  "name": "@lambda-fluid/benchmark",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "check": "vp check"
  },
  "dependencies": {
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/worker": "workspace:*"
  },
  "devDependencies": {
    "@types/node": "^25.9.0"
  }
}

```

### packages/protocol/package.json

```
{
  "name": "@lambda-fluid/protocol",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts",
    "./schema": "./src/schema.ts"
  },
  "scripts": {
    "check": "vp check",
    "test": "vp test run packages/protocol/test --passWithNoTests"
  },
  "dependencies": {
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@effect/vitest": "4.0.0-beta.98",
    "@types/node": "^25.9.0"
  }
}

```

### packages/worker/package.json

```
{
  "name": "@lambda-fluid/worker",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "check": "vp check",
    "test": "vp test run packages/worker/test"
  },
  "dependencies": {
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/tunnel": "workspace:*",
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@effect/vitest": "4.0.0-beta.98",
    "@types/node": "^25.9.0",
    "vitest": "catalog:"
  }
}

```

### packages/tunnel/package.json

```
{
  "name": "@lambda-fluid/tunnel",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "check": "vp check",
    "test": "vp test run packages/tunnel/test"
  },
  "dependencies": {
    "@effect/platform-node": "4.0.0-beta.98",
    "@lambda-fluid/protocol": "workspace:*",
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@effect/vitest": "4.0.0-beta.98",
    "@types/node": "^25.9.0",
    "vitest": "catalog:"
  }
}

```

### packages/aws-runtime/package.json

```
{
  "name": "@lambda-fluid/aws-runtime",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "check": "vp check",
    "test": "vp test run packages/aws-runtime/test --passWithNoTests"
  },
  "dependencies": {
    "@distilled.cloud/aws": "0.29.1",
    "@effect/platform-node": "4.0.0-beta.98",
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/worker": "workspace:*",
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@effect/vitest": "4.0.0-beta.98",
    "@types/node": "^25.9.0",
    "vitest": "catalog:"
  }
}

```

### packages/benchmark-cli/package.json

```
{
  "name": "@lambda-fluid/benchmark-cli",
  "private": true,
  "bin": {
    "bench": "./dist/cli.js"
  },
  "type": "module",
  "scripts": {
    "build": "vp build --ssr src/cli.ts --outDir dist",
    "check": "vp check"
  },
  "dependencies": {
    "@effect/platform-node": "4.0.0-beta.98",
    "@lambda-fluid/benchmark": "workspace:*",
    "@lambda-fluid/orchestrator": "workspace:*",
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/worker": "workspace:*",
    "effect": "4.0.0-beta.98",
    "vite": "catalog:"
  },
  "devDependencies": {
    "@types/node": "^25.9.0"
  }
}

```

### packages/orchestrator/package.json

```
{
  "name": "@lambda-fluid/orchestrator",
  "private": true,
  "type": "module",
  "exports": {
    ".": "./src/index.ts"
  },
  "scripts": {
    "check": "vp check",
    "test": "vp test run packages/orchestrator/test"
  },
  "dependencies": {
    "@lambda-fluid/protocol": "workspace:*",
    "@lambda-fluid/tunnel": "workspace:*",
    "effect": "4.0.0-beta.98"
  },
  "devDependencies": {
    "@effect/platform-node": "4.0.0-beta.98",
    "@effect/vitest": "4.0.0-beta.98",
    "@lambda-fluid/benchmark": "workspace:*",
    "@lambda-fluid/worker": "workspace:*",
    "@types/node": "^25.9.0",
    "vitest": "catalog:"
  }
}

```

[76 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]