Merge pull request #108 from gmoon/chore/lattice-fill-gaps

gmoon · web-flow · commit bb176de78ac6 · 2026-05-23T19:13:58.000-04:00
chore(lattice): fill representation gaps (tiers 1-4)
diff --git a/.lattice/implementations/core-001.yaml b/.lattice/implementations/core-001.yaml
@@ -7,14 +7,12 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:00.991022+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: src/index.ts
-  - path: test/streaming-memory.test.ts
-  - path: vitest.config.ts
-  test_command: npm test
+meta: {}
 edges:
   satisfies:
   - target: REQ-CORE-001
     version: 1.0.0
+  validates:
+  - target: THX-SDK-PUBLIC-API
+    version: 1.0.0
+    rationale: Zero-any rewrite of send() proves the typed-output approach replaces middleware-stack hacking without functional loss
diff --git a/.lattice/implementations/core-002.yaml b/.lattice/implementations/core-002.yaml
@@ -7,16 +7,12 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:12.101544+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: src/errors.ts
-  - path: src/index.ts
-  - path: test/s3proxy.test.ts
-  - path: test/helpers/http-mocks.ts
-  - path: scripts/smoke-examples.sh
-  test_command: npm test
+meta: {}
 edges:
   satisfies:
   - target: REQ-CORE-002
     version: 1.0.0
+  validates:
+  - target: THX-TYPED-ERRORS
+    version: 1.0.0
+    rationale: All four error classes throw correctly with cause attached; examples and CI confirm consumers can render the right HTTP status
diff --git a/.lattice/implementations/core-003.yaml b/.lattice/implementations/core-003.yaml
@@ -7,15 +7,12 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:12.130405+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: src/index.ts
-  - path: src/types.ts
-  - path: test/s3proxy.test.ts
-  - path: README.md
-  test_command: npm test
+meta: {}
 edges:
   satisfies:
   - target: REQ-CORE-003
     version: 1.0.0
+  validates:
+  - target: THX-FAIL-FAST-OPT-OUT
+    version: 1.0.0
+    rationale: 'Test cases confirm both branches: default true rejects on unreachable bucket, false defers to readiness probe'
diff --git a/.lattice/implementations/core-004.yaml b/.lattice/implementations/core-004.yaml
@@ -7,22 +7,15 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:28.964517+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: src/index.ts
-  - path: src/request-parser.ts
-  - path: src/s3-gateway.ts
-  - path: src/types.ts
-  - path: examples/express-basic.ts
-  - path: examples/fastify-basic.ts
-  - path: examples/fastify-docker.ts
-  - path: examples/http.ts
-  - path: test/fetch.test.ts
-  - path: test/parse-request.test.ts
-  - path: test/s3proxy.test.ts
-  test_command: npm test && npm run type-check && bash scripts/smoke-examples.sh
+meta: {}
 edges:
   satisfies:
   - target: REQ-CORE-004
     version: 1.0.0
+  validates:
+  - target: THX-DECOMPOSE
+    version: 1.0.0
+    rationale: Parser + gateway + orchestrator split shipped without breaking the public API; src/index.ts dropped from 288 to ~125 LOC
+  - target: THX-PURE-FETCH
+    version: 1.0.0
+    rationale: 'proxy.fetch(req) returning {stream, status, headers} works end-to-end through real S3 (artillery: 300/300 reqs, ~990MB streamed, 0 failures)'
diff --git a/.lattice/implementations/example-001.yaml b/.lattice/implementations/example-001.yaml
@@ -7,15 +7,15 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:29.055437+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: examples/hono-basic.ts
-  - path: scripts/smoke-examples.sh
-  - path: README.md
-  - path: package.json
-  test_command: bash scripts/smoke-examples.sh
+meta: {}
 edges:
   satisfies:
   - target: REQ-EXAMPLE-001
     version: 1.0.0
+  validates:
+  - target: THX-PURE-FETCH
+    version: 1.0.0
+    rationale: Hono uses the same proxy.fetch() as Express/Fastify, with no library changes — direct evidence of framework-agnostic design
+  - target: THX-WEB-STANDARDS
+    version: 1.0.0
+    rationale: examples/hono-basic.ts ships on Node via @hono/node-server with measured parity (mean=55-58ms across all 3 frameworks); same code runs on Bun/Workers/Deno where the conversion layer disappears
diff --git a/.lattice/implementations/test-001.yaml b/.lattice/implementations/test-001.yaml
@@ -7,18 +7,12 @@ version: 1.0.0
 created_at: 2026-05-11T22:57:29.011183+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  language: typescript
-  files:
-  - path: test/s3proxy.test.ts
-  - path: test/fetch.test.ts
-  - path: test/concurrent.test.ts
-  - path: test/streaming-memory.test.ts
-  - path: test/helpers/http-mocks.ts
-  - path: test/helpers/aws-mock.ts
-  - path: scripts/smoke-examples.sh
-  test_command: npm test && bash scripts/smoke-examples.sh
+meta: {}
 edges:
   satisfies:
   - target: REQ-TEST-001
     version: 1.0.0
+  validates:
+  - target: THX-NO-BUFFERING
+    version: 1.0.0
+    rationale: Streaming-memory test pipes 100MB through proxy.fetch() asserting peak RSS delta < 50MB; concurrent test confirms 10 parallel streams produce distinct bytes (no shared buffer)
diff --git a/.lattice/requirements/build/002-scope-pool-forks--with---expose-gc--to-s.yaml b/.lattice/requirements/build/002-scope-pool-forks--with---expose-gc--to-s.yaml
@@ -0,0 +1,23 @@
+id: REQ-BUILD-002
+type: requirement
+title: Scope pool:forks (with --expose-gc) to streaming test only
+body: vitest.config.ts uses pool:'forks' + execArgv:['--expose-gc'] so test/streaming-memory.test.ts can call global.gc(). All other test files pay the fork startup cost too (~100ms/file × ~10 files = ~1s wall time per run). Use vitest 'projects' or per-file pool config to fork only the streaming test.
+status: active
+version: 1.0.0
+created_at: 2026-05-23T22:57:34.379746+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+priority: P2
+category: BUILD
+tags:
+- perf
+- test-config
+resolution:
+  status: deferred
+  reason: <0.5s saved per test run after vitest 4 oxc speedup; vitest 3.x→4.x workspace/projects config adds more complexity than the saving justifies. Revisit if test suite grows materially.
+  resolved_at: 2026-05-23T22:57:34.408591+00:00
+  resolved_by: agent:claude-2026-05-23
+edges:
+  derives_from:
+  - target: THX-DECOMPOSE
+    version: 1.0.0
diff --git a/.lattice/requirements/core/001-replace-aws-sdk-middleware-stack-hack-wi.yaml b/.lattice/requirements/core/001-replace-aws-sdk-middleware-stack-hack-wi.yaml
@@ -20,3 +20,6 @@ edges:
   derives_from:
   - target: THX-SDK-PUBLIC-API
     version: 1.0.0
+  - target: THX-NO-BUFFERING
+    version: 1.0.0
+    rationale: The new middleware-replacement path was required to not buffer; streaming-memory test asserts this
diff --git a/.lattice/requirements/core/004-introduce-proxy-fetch----decompose-into-.yaml b/.lattice/requirements/core/004-introduce-proxy-fetch----decompose-into-.yaml
@@ -23,3 +23,6 @@ edges:
     version: 1.0.0
   - target: THX-DECOMPOSE
     version: 1.0.0
+  - target: THX-CORE-VALUE
+    version: 1.0.0
+    rationale: proxy.fetch() is the public API surface through which the value prop (stream-without-buffering) is delivered to consumers
diff --git a/.lattice/requirements/core/005-remove-vestigial-public-proxy-isinitiali.yaml b/.lattice/requirements/core/005-remove-vestigial-public-proxy-isinitiali.yaml
@@ -0,0 +1,23 @@
+id: REQ-CORE-005
+type: requirement
+title: Remove vestigial public proxy.isInitialized()
+body: 'Public isInitialized() exists for v3 backwards-compat. After v4 it does void this.gateway.isInitialized() — two indirections to throw if uninitialized. The method''s name suggests a predicate but it throws. Removing simplifies the public API (one less method to document/test) and consolidates ''uninitialized'' detection to the gateway''s lazy client getter. BREAKING but trivial: callers that used it can just call init() and trust the next call.'
+status: active
+version: 1.0.0
+created_at: 2026-05-23T22:57:34.337798+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+priority: P2
+category: CORE
+tags:
+- cleanup
+- breaking
+resolution:
+  status: deferred
+  reason: Out of scope for the v4 prompt. The method works; removing is cleanup beyond the v4 surface. Revisit when next breaking change PR opens.
+  resolved_at: 2026-05-23T22:57:34.371684+00:00
+  resolved_by: agent:claude-2026-05-23
+edges:
+  derives_from:
+  - target: THX-DECOMPOSE
+    version: 1.0.0
diff --git a/.lattice/requirements/core/006-widen-httprequest--headers---to-headers-.yaml b/.lattice/requirements/core/006-widen-httprequest--headers---to-headers-.yaml
@@ -0,0 +1,30 @@
+id: REQ-CORE-006
+type: requirement
+title: 'Widen HttpRequest[''headers''] to Headers | Record (path B from #104)'
+body: 'Current HttpRequest.headers is Record<string, string|string[]> (Node convention). Frameworks built on Web Standards (Hono, future Remix/SvelteKit/Vercel handlers) hand you a Web Headers object — examples/hono-basic.ts adapts at the boundary with Object.fromEntries. Widening the type to accept both would remove the adapter step but adds dual-shape complexity to the parser. The decision in #104 was ''wait for a second framework to force it'' — when a second framework lands needing the same adapter, the case for B strengthens.'
+status: active
+version: 1.0.0
+created_at: 2026-05-23T22:57:58.229935+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+priority: P2
+category: CORE
+tags:
+- api
+- types
+- framework
+resolution:
+  status: deferred
+  reason: Path A (adapter at example boundary) is correct until a second Web-Standards framework forces the same conversion. Re-evaluate when adding a Remix/SvelteKit/Vercel example or when a user files an issue about the cast.
+  resolved_at: 2026-05-23T22:57:58.256303+00:00
+  resolved_by: agent:claude-2026-05-23
+edges:
+  derives_from:
+  - target: THX-PURE-FETCH
+    version: 1.0.0
+  - target: THX-WEB-STANDARDS
+    version: 1.0.0
+  depends_on:
+  - target: REQ-CORE-004
+    version: 1.0.0
+    rationale: Path B widens HttpRequest['headers'] — the type only became public in REQ-CORE-004
diff --git a/.lattice/requirements/example/001-hono-example-for-web-standards-runtimes.yaml b/.lattice/requirements/example/001-hono-example-for-web-standards-runtimes.yaml
@@ -23,3 +23,7 @@ edges:
     version: 1.0.0
   - target: THX-WEB-STANDARDS
     version: 1.0.0
+  depends_on:
+  - target: REQ-CORE-004
+    version: 1.0.0
+    rationale: 'Hono example uses proxy.fetch(); couldn''t be written before #100 shipped it'
diff --git a/.lattice/requirements/example/002-hono-docker-integration-parallel-to-fast.yaml b/.lattice/requirements/example/002-hono-docker-integration-parallel-to-fast.yaml
@@ -0,0 +1,28 @@
+id: REQ-EXAMPLE-002
+type: requirement
+title: Hono Docker integration parallel to fastify-docker
+body: examples/fastify-docker.ts is the integration test target (make test-validation-docker). If Hono becomes a primary deployment story, we'd want examples/hono-docker.ts with its own Dockerfile and Makefile target — to test that proxy.fetch() via Hono + @hono/node-server holds under the 24-test validation suite and artillery load.
+status: active
+version: 1.0.0
+created_at: 2026-05-23T22:57:58.183754+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+priority: P2
+category: EXAMPLE
+tags:
+- hono
+- docker
+- integration
+resolution:
+  status: deferred
+  reason: No published Hono Docker variant of s3proxy exists; the smoke gate already validates examples/hono-basic.ts boots and serves correctly. Revisit if someone publishes a hono-on-bun or hono-on-workers deployment story.
+  resolved_at: 2026-05-23T22:57:58.223057+00:00
+  resolved_by: agent:claude-2026-05-23
+edges:
+  derives_from:
+  - target: THX-WEB-STANDARDS
+    version: 1.0.0
+  depends_on:
+  - target: REQ-EXAMPLE-001
+    version: 1.0.0
+    rationale: Hono Docker target needs the basic Hono example first
diff --git a/.lattice/requirements/test/001-behavioral-coverage--zero--proxy-as-any-.yaml b/.lattice/requirements/test/001-behavioral-coverage--zero--proxy-as-any-.yaml
@@ -23,3 +23,6 @@ edges:
     version: 1.0.0
   - target: THX-PURE-FETCH
     version: 1.0.0
+  - target: THX-NO-BUFFERING
+    version: 1.0.0
+    rationale: 100MB streaming-memory test + concurrent fetch test exist specifically to enforce the no-buffering constraint
diff --git a/.lattice/sources/express5-splat.yaml b/.lattice/sources/express5-splat.yaml
@@ -0,0 +1,13 @@
+id: SRC-EXPRESS5-SPLAT
+type: source
+title: Express 5's path-to-regexp 6+ requires named wildcards
+body: 'Express 4 accepted app.get(''/*'', ...) as a catch-all. Express 5 upgraded path-to-regexp to v6+, which requires named parameters: app.get(''/*splat'', ...) — the wildcard must have a name. Unnamed ''/*'' throws ''TypeError: Missing parameter name at 2'' at route registration time, crashing the server on startup. The v4 smoke gate caught this on its first run; the fix is a one-character change in examples/express-basic.ts.'
+status: active
+version: 1.0.0
+created_at: 2026-05-11T23:43:08.587584+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+meta:
+  url: https://expressjs.com/en/guide/migrating-5.html
+  reliability: industry
+  retrieved_at: 2026-05-11
diff --git a/.lattice/sources/ts6-types.yaml b/.lattice/sources/ts6-types.yaml
@@ -0,0 +1,13 @@
+id: SRC-TS6-TYPES
+type: source
+title: TypeScript 6 stops auto-including @types/* when lib is explicit
+body: 'TS 6 changed @types/* auto-inclusion semantics. In TS 5 and earlier, with ''lib'' set explicitly (e.g. [''ES2022'']), @types/node was still implicitly available. In TS 6, you must opt-in via ''types'': [''node''] in compilerOptions. Without the opt-in: ''Cannot find name node:events'', ''Cannot find namespace NodeJS'', ''Property captureStackTrace does not exist on type ErrorConstructor'', etc. Fix: add ''types'': [''node''] to tsconfig.base.json. Bit us during the TS 5→6 bump in PR #105.'
+status: active
+version: 1.0.0
+created_at: 2026-05-11T23:43:08.552197+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+meta:
+  url: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types
+  reliability: industry
+  retrieved_at: 2026-05-11
diff --git a/.lattice/sources/vitest4-migration.yaml b/.lattice/sources/vitest4-migration.yaml
@@ -0,0 +1,13 @@
+id: SRC-VITEST4-MIGRATION
+type: source
+title: 'Vitest 4: poolOptions flattened, oxc replaces esbuild'
+body: 'Two breaking changes in vitest 4: (1) test.poolOptions was removed; pool-specific options are now top-level under test. Migrate test.poolOptions.forks.execArgv → test.forks.execArgv. (2) Default transformer is now oxc, not esbuild. Setting esbuild config warns ''both esbuild and oxc options were set; oxc options will be used and esbuild options will be ignored.'' We dropped the esbuild target:''node18'' since engines already requires Node 22.13+. Bit us during the vitest 3→4 bump in PR #105.'
+status: active
+version: 1.0.0
+created_at: 2026-05-11T23:43:08.614754+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+meta:
+  url: https://vitest.dev/guide/migration#migrating-to-vitest-4-0
+  reliability: industry
+  retrieved_at: 2026-05-11
diff --git a/.lattice/theses/core-value.yaml b/.lattice/theses/core-value.yaml
@@ -0,0 +1,16 @@
+id: THX-CORE-VALUE
+type: thesis
+title: Stream S3 objects to HTTP clients without buffering on the proxy
+body: 's3proxy turns any S3 bucket into a high-performance web server. The core value: files stream directly from S3 to users with no intermediate buffering on the proxy host. This is the difference between s3proxy and ''an Express handler that calls S3Client.send()'' — bounded memory, sub-millisecond TTFB, range-request passthrough, no disk involvement. Every other thesis derives from this constraint.'
+status: active
+version: 1.0.0
+created_at: 2026-05-11T23:42:54.076405+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+meta:
+  category: value_prop
+  confidence: 0.99
+edges:
+  supported_by:
+  - target: SRC-V4-MIGRATION
+    version: 1.0.0
diff --git a/.lattice/theses/decompose.yaml b/.lattice/theses/decompose.yaml
@@ -7,10 +7,14 @@ version: 1.0.0
 created_at: 2026-05-11T22:55:48.056504+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  category: technical
-  confidence: 0.9
+meta: {}
 edges:
   supported_by:
   - target: SRC-V4-PROMPT
     version: 1.0.0
+  - target: SRC-TS6-TYPES
+    version: 1.0.0
+    rationale: Shared tsconfig.base.json absorbs the TS 6 types:['node'] fix in one place; without the decomposition every config file would need patching
+  - target: SRC-VITEST4-MIGRATION
+    version: 1.0.0
+    rationale: Shared vitest.shared.ts + thin per-config files made the vitest 4 poolOptions flattening + esbuild→oxc migration a 3-line change instead of N
diff --git a/.lattice/theses/no-buffering.yaml b/.lattice/theses/no-buffering.yaml
@@ -0,0 +1,20 @@
+id: THX-NO-BUFFERING
+type: thesis
+title: Memory usage must be bounded by chunk size, not object size
+body: 'Hard constraint: at no point may the proxy hold more than a small constant of bytes from a single S3 object. A 10GB AI model stream must not allocate 10GB on the proxy. This forbids any internal API that reads the full body (no Buffer.concat, no await response.body.text(), no internal caching of bodies). Validated continuously by test/streaming-memory.test.ts (100MB body, peak RSS delta < 50MB) and the artillery suite. Drives backpressure preservation through every framework adapter.'
+status: active
+version: 1.0.0
+created_at: 2026-05-11T23:42:54.109725+00:00
+created_by: agent:claude
+requested_by: George Moon <george.moon@gmail.com>
+meta: {}
+edges:
+  supported_by:
+  - target: SRC-V4-PROMPT
+    version: 1.0.0
+  - target: SRC-V4-MIGRATION
+    version: 1.0.0
+  derives_from:
+  - target: THX-CORE-VALUE
+    version: 1.0.0
+    rationale: The no-buffering constraint is the technical expression of the core value prop
diff --git a/.lattice/theses/pure-fetch.yaml b/.lattice/theses/pure-fetch.yaml
@@ -7,9 +7,7 @@ version: 1.0.0
 created_at: 2026-05-11T22:55:50.706349+00:00
 created_by: agent:claude
 requested_by: George Moon <george.moon@gmail.com>
-meta:
-  category: value_prop
-  confidence: 0.95
+meta: {}
 edges:
   supported_by:
   - target: SRC-V4-PROMPT
@@ -18,3 +16,10 @@ edges:
     version: 1.0.0
   - target: SRC-HONO-PR
     version: 1.0.0
+  - target: SRC-EXPRESS5-SPLAT
+    version: 1.0.0
+    rationale: Express 5 splat-syntax change is exactly the kind of framework-specific quirk that pure proxy.fetch() insulates the library from — the smoke gate caught it at the example layer, not in src/
+  derives_from:
+  - target: THX-CORE-VALUE
+    version: 1.0.0
+    rationale: Stream-without-buffering value prop requires an API that doesn't force callers to mutate a Node res; pure fetch enables any host
