V2 phase 1

.gitignore

@@ -46,4 +46,5 @@ profile.cov
 
 !docs/internals.md
 !docs/env.md
-!docs/waylog-sdk-contract.md
+!docs/waylog-sdk-contract.md
+!docs/sdk-examples.md

Makefile

@@ -1,6 +1,6 @@
 SHELL := /bin/sh
 
-.PHONY: help build build-examples ingest ingest-mcp waylog waylog-live checkout test test-race test-sdk lint ci fmt vet vet-sdk clean kafka-up kafka-down demo demo-stop micro-demo micro-demo-stop docker-build docker-up docker-down docker-reset docker-dev docker-prod ts-install ts-build ts-test
+.PHONY: help build build-examples ingest ingest-mcp waylog waylog-live checkout test test-race test-sdk lint ci fmt vet vet-sdk clean kafka-up kafka-down demo demo-stop micro-demo micro-demo-stop docker-build docker-up docker-down docker-reset docker-dev docker-prod ts-install ts-build ts-test bench-gate
 
 help:
 	@echo "Targets:"
@@ -99,6 +99,9 @@ check-doc-links:
 check-rollup-contract:
 	@bash scripts/check-rollup-contract.sh
 
+bench-gate: ## Enforce v2 SDK §4.4.1 perf budgets (optional; not in `ci` yet)
+	@bash scripts/bench-gate.sh
+
 clean:
 	rm -f ingest checkout waylog bridge api-gateway checkout-demo db-demo payment-demo waylog-live
 

README.md

@@ -57,24 +57,27 @@ import { waylog, useLogger } from "@waylog/sdk/express";
 app.use(waylog({
   service: "checkout",
   env: "prod",
-  endpoint: "http://localhost:8080",
+  ingestUrl: "http://localhost:8080",
   apiKey: process.env.WAYLOG_WRITE_KEY,
 }));
 
 app.post("/buy", (req, res) => {
-  useLogger(req).set({ user: { id: req.user.id, tier: "vip" } });
+  useLogger(req).info("cart loaded", { user_id: req.user.id, tier: "vip" });
   res.sendStatus(200);
 });
 ```
 
-`@waylog/sdk` is ESM-only, Node 18+, and ships Express and Hono middleware (`@waylog/sdk/express`, `@waylog/sdk/hono`). `createLogger().withRequest().set().emit()` is also exposed for non-middleware use.
+`@waylog/sdk` is ESM-only, Node 18+, and ships standalone core APIs plus Express, Hono, Next.js, and NestJS entrypoints (`@waylog/sdk/express`, `@waylog/sdk/hono`, `@waylog/sdk/next`, `@waylog/sdk/nest`).
 
 ### Go SDK
 
 ```go
 import (
-    waylog "github.com/sssmaran/WaylogCLI/pkg"
-    wayloghttp "github.com/sssmaran/WaylogCLI/pkg/http"
+    "context"
+    "net/http"
+
+    waylog "github.com/sssmaran/WaylogCLI/pkg/waylog/v2"
+    wayloghttp "github.com/sssmaran/WaylogCLI/pkg/waylog/http"
 )
 
 func main() {
@@ -86,11 +89,11 @@ func main() {
     })
     defer waylog.Shutdown(context.Background())
 
-    http.Handle("/", wayloghttp.Middleware(yourHandler))
+    http.Handle("/", wayloghttp.HTTP(yourHandler))
 }
 ```
 
-Schema 1.1 helpers (`WithErrorReason`, `WithErrorPath`, `WithParentRequestID`, `WithMetadataKey`, `WithAttempt`, `WithRetry`) are additive.
+The recommended SDK path is framework middleware plus `waylog.From(ctx)` / `useLogger(...)` inside handlers. Low-level request APIs such as `Begin`, `Finalize`, and `setField` are for adapter authors, tests, and unusual custom integrations. Full copy-paste examples for `net/http`, chi, gin, echo, standalone TypeScript, Express, Hono, Next.js, and NestJS are in [`docs/sdk-examples.md`](docs/sdk-examples.md).
 
 ### OTLP/HTTP traces
 
@@ -267,7 +270,7 @@ Public alpha. APIs may break before 1.0.
 
 **Shipped:**
 
-- Go SDK (schema 1.1 accessors) and TypeScript SDK (`@waylog/sdk`, ESM, Node 18+, Express + Hono middleware)
+- Go SDK v2 (`net/http`, chi, gin, echo) and TypeScript SDK v2 (`@waylog/sdk`, ESM, Node 18+, standalone core, Express, Hono, Next.js, NestJS)
 - OTLP/HTTP traces at `/v1/otlp/v1/traces` (Phase A — traces only)
 - durable ingest with WAL + replay
 - hot graph with flattened 3-node model + dedicated trace store

docs/sdk-examples.md

@@ -0,0 +1,183 @@
+# SDK Examples
+
+These are the recommended copy-paste integration shapes for Waylog v2. Prefer framework middleware plus a request-scoped logger. Use low-level `Begin` / `Finalize` APIs only when writing a custom adapter or a deterministic test/smoke driver.
+
+## Go `net/http`
+
+```go
+package main
+
+import (
+	"context"
+	"net/http"
+
+	waylog "github.com/sssmaran/WaylogCLI/pkg/waylog/v2"
+	wayloghttp "github.com/sssmaran/WaylogCLI/pkg/waylog/http"
+)
+
+func main() {
+	_ = waylog.Init(waylog.Config{
+		Service:   "checkout",
+		Env:       "prod",
+		IngestURL: "http://localhost:8080",
+	})
+	defer waylog.Shutdown(context.Background())
+
+	mux := http.NewServeMux()
+	mux.Handle("/buy", wayloghttp.HTTP(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		waylog.From(r.Context()).Info("cart loaded", waylog.F{"cart_id": "c_123"})
+		w.WriteHeader(http.StatusOK)
+	})))
+
+	_ = http.ListenAndServe(":3000", mux)
+}
+```
+
+## Go chi
+
+```go
+import (
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	waylogchi "github.com/sssmaran/WaylogCLI/pkg/waylog/chi"
+	waylog "github.com/sssmaran/WaylogCLI/pkg/waylog/v2"
+)
+
+r := chi.NewRouter()
+r.Use(waylogchi.Middleware)
+r.Post("/buy/{id}", func(w http.ResponseWriter, r *http.Request) {
+	waylog.From(r.Context()).Info("checkout started")
+	w.WriteHeader(http.StatusOK)
+})
+```
+
+## Go gin
+
+```go
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	wayloggin "github.com/sssmaran/WaylogCLI/pkg/waylog/gin"
+	waylog "github.com/sssmaran/WaylogCLI/pkg/waylog/v2"
+)
+
+r := gin.New()
+r.Use(wayloggin.Middleware())
+r.POST("/buy/:id", func(c *gin.Context) {
+	waylog.From(c.Request.Context()).Info("checkout started")
+	c.Status(http.StatusOK)
+})
+```
+
+## Go echo
+
+```go
+import (
+	"net/http"
+
+	"github.com/labstack/echo/v4"
+	waylogecho "github.com/sssmaran/WaylogCLI/pkg/waylog/echo"
+	waylog "github.com/sssmaran/WaylogCLI/pkg/waylog/v2"
+)
+
+e := echo.New()
+e.Use(waylogecho.Middleware())
+e.POST("/buy/:id", func(c echo.Context) error {
+	waylog.From(c.Request().Context()).Info("checkout started")
+	return c.NoContent(http.StatusOK)
+})
+```
+
+## TypeScript Standalone
+
+```ts
+import { begin, finalize, from, init, setField, step } from "@waylog/sdk";
+
+init({
+  service: "worker",
+  env: "prod",
+  ingestUrl: "http://localhost:8080",
+  apiKey: process.env.WAYLOG_WRITE_KEY,
+});
+
+const ctx = begin({});
+setField(ctx, "http", { method: "JOB", route: "queue:purchase", status: 200 });
+await step(ctx, "payment.charge", async () => {
+  from(ctx).info("charging payment", { cart_id: "c_123" });
+});
+await finalize(ctx);
+```
+
+## TypeScript Express
+
+```ts
+import { waylog, useLogger } from "@waylog/sdk/express";
+
+app.use(waylog({
+  service: "checkout",
+  env: "prod",
+  ingestUrl: "http://localhost:8080",
+  apiKey: process.env.WAYLOG_WRITE_KEY,
+}));
+
+app.post("/buy/:id", (req, res) => {
+  useLogger(req).info("checkout started", { cart_id: req.params.id });
+  res.sendStatus(200);
+});
+```
+
+## TypeScript Hono
+
+```ts
+import { Hono } from "hono";
+import { waylog, useLogger } from "@waylog/sdk/hono";
+
+const app = new Hono();
+app.use("*", waylog({
+  service: "checkout",
+  env: "prod",
+  ingestUrl: "http://localhost:8080",
+}));
+
+app.post("/buy/:id", (c) => {
+  useLogger(c).info("checkout started", { cart_id: c.req.param("id") });
+  return c.text("ok");
+});
+```
+
+## TypeScript Next.js
+
+```ts
+import { middleware as withWaylog, useLogger } from "@waylog/sdk/next";
+
+export const POST = withWaylog({
+  service: "checkout",
+  env: "prod",
+  ingestUrl: "http://localhost:8080",
+}, async (_req, ctx) => {
+  useLogger(ctx).info("checkout started");
+  return Response.json({ ok: true }, { status: 200 });
+});
+```
+
+## TypeScript NestJS
+
+```ts
+import { MiddlewareConsumer, Module, NestModule } from "@nestjs/common";
+import { middleware as waylog } from "@waylog/sdk/nest";
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(waylog({
+        service: "checkout",
+        env: "prod",
+        ingestUrl: "http://localhost:8080",
+      }))
+      .forRoutes("*");
+  }
+}
+```

go.work.sum

@@ -6,17 +6,49 @@ github.com/aymanbagabas/go-udiff v0.3.1/go.mod h1:G0fsKmG+P6ylD0r6N/KgQD/nWzgfnl
 github.com/bits-and-blooms/bitset v1.24.4/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/charmbracelet/harmonica v0.2.0/go.mod h1:KSri/1RMQOZLbw7AHqgcBycp8pgJnQMYYT8QZRqZ1Ao=
 github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
+github.com/gabriel-vasile/mimetype v1.4.3 h1:in2uUcidCuFcDKtdcBxlR0rJ1+fsokWf+uqxgUFjbI0=
+github.com/gabriel-vasile/mimetype v1.4.3/go.mod h1:d8uq/6HKRL6CGdk+aubisF/M5GcPfT7nKyLpA0lbSSk=
+github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
+github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
+github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
+github.com/gin-gonic/gin v1.10.1/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
+github.com/go-chi/chi/v5 v5.2.3 h1:WQIt9uxdsAbgIYgid+BpYc+liqQZGMHRaUwp0JUcvdE=
+github.com/go-chi/chi/v5 v5.2.3/go.mod h1:L2yAIGWB3H+phAw1NxKwWM+7eUH/lU8pOMm5hHcoops=
+github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
+github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
+github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
+github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
+github.com/go-playground/validator/v10 v10.20.0 h1:K9ISHbSaI0lyB2eWMPJo+kOS/FBExVwjEviJTixqxL8=
+github.com/go-playground/validator/v10 v10.20.0/go.mod h1:dbuPbCMFw/DrkbEynArYaCwl3amGuJotoKCe95atGMM=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0 h1:HWRh5R2+9EifMyIHV7ZV+MIZqgz+PMpZ14Jynv3O2Zs=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.28.0/go.mod h1:JfhWUomR1baixubs02l85lZYYOm7LV6om4ceouMv45c=
 github.com/jpillora/backoff v1.0.0/go.mod h1:J/6gKK9jxlEcS3zixgDgUAsiuZ7yrSoa/FX5e0EB2j4=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/julienschmidt/httprouter v1.3.0/go.mod h1:JR6WtHb+2LUe8TCKY3cZOxFyyO8IZAc4RVcycCCAKdM=
+github.com/labstack/echo/v4 v4.13.4 h1:oTZZW+T3s9gAu5L8vmzihV7/lkXGZuITzTQkTEhcXEA=
+github.com/labstack/echo/v4 v4.13.4/go.mod h1:g63b33BZ5vZzcIUF8AtRH40DrTlXnx4UMC8rBdndmjQ=
+github.com/labstack/gommon v0.4.2 h1:F8qTUNXgG1+6WQmqoUWnz8WiEU60mXVVw0P4ht1WRA0=
+github.com/labstack/gommon v0.4.2/go.mod h1:QlUFxVM+SNXhDL/Z7YhocGIBYOiwB0mXm1+1bAPHPyU=
+github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
+github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f/go.mod h1:qRWi+5nqEBWmkhHvq77mSJWrCKwh8bxhgT7d/eI7P4U=
+github.com/pelletier/go-toml/v2 v2.2.2 h1:aYUidT7k73Pcl9nb2gScu7NSrKCSHIDE89b3+6Wq+LM=
+github.com/pelletier/go-toml/v2 v2.2.2/go.mod h1:1t835xjRzz80PqgE6HHgN2JOsmgYu/h4qDAS4n929Rs=
 github.com/sahilm/fuzzy v0.1.1/go.mod h1:VFvziUEIMCrT6A6tw2RFIXPXXmzXbOsSHF0DOI8ZK9Y=
+github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
+github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasttemplate v1.2.2 h1:lxLXG0uE3Qnshl9QyaK6XJxMXlQZELvChBOCmQD0Loo=
+github.com/valyala/fasttemplate v1.2.2/go.mod h1:KHLXt3tVN2HBp8eijSv/kGJopbvo7S+qRAEEKiv+SiQ=
 github.com/xhit/go-str2duration/v2 v2.1.0/go.mod h1:ohY8p+0f07DiV6Em5LKB0s2YpLtXVyJfNt1+BlmyAsU=
+golang.org/x/crypto v0.38.0 h1:jt+WWG8IZlBnVbomuhg2Mdq0+BBQaHbtqHEFEigjUV8=
+golang.org/x/crypto v0.38.0/go.mod h1:MvrbAqul58NNYPKnOra203SB9vpuZW0e+RRZV+Ggqjw=
 golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
 golang.org/x/tools/go/expect v0.1.1-deprecated/go.mod h1:eihoPOH+FgIqa3FpoTwguz/bVUSGBlGQU67vpBeOrBY=
 golang.org/x/tools/go/packages/packagestest v0.1.1-deprecated/go.mod h1:RVAQXBGNv1ib0J382/DPCRS/BPnsGebyM1Gj5VSDpG8=

packages/waylog-ts/examples/e2e-emit.ts

@@ -1,36 +1,36 @@
-// e2e-emit.ts emits a single TS-SDK trace (1 request) to the ingest server
-// and prints the trace_id on stdout. Used by scripts/e2e-mark2.sh to drive
-// the TypeScript SDK path.
-//
-// Runner: vite-node (available in local node_modules/.bin after `npm install`
-// inside packages/waylog-ts — ships with vitest).
+// e2e-emit.ts is a low-level schema 2.0 smoke driver, not the recommended
+// user-facing integration example. Real apps should usually use framework
+// middleware (`@waylog/sdk/express`, `@waylog/sdk/hono`, etc.) and
+// `useLogger(...)`. This file exercises the standalone core directly so the
+// e2e path can emit a deterministic payment-failure event without depending
+// on any framework adapter.
 
-import { createLogger } from "../src/index.js";
+import { begin, fail, finalize, from, init, newError, recordOutgoingSpan, setField, setHTTPStatus, stepSync, traceId } from "../src/index.js";
 
-const endpoint = process.env.INGEST_URL ?? "http://localhost:8080";
-
-const logger = createLogger({
-  endpoint,
+init({
+  ingestUrl: process.env.INGEST_URL ?? "http://localhost:8080",
   service: "ts-e2e",
   env: "dev",
   version: "0.1.0",
-  batchSize: 1,
-  flushIntervalMs: 100,
-});
-
-const req = logger.withRequest({
-  flow: "purchase",
-  user: { id: "ts-e2e-user", tier: "standard", region: "us-east-1" },
-  httpMethod: "GET",
-  routeTemplate: "/api/e2e",
 });
 
-// Extract the trace_id from the outbound traceparent: "00-<trace>-<span>-<flags>".
-const traceId = req.traceparent().split("-")[1]!;
-
-req.emit({ success: true, status_code: 200 });
-
-await logger.flush();
-await logger.close();
-
-console.log(traceId);
+const ctx = begin({});
+setField(ctx, "http", { method: "POST", route: "/api/e2e", status: 200 });
+setField(ctx, "user", { id: "ts-e2e-user", tier: "standard", region: "us-east-1" });
+
+stepSync(ctx, "db.load_cart", () => undefined);
+const err = newError("PMT_502", { reason: "upstream gateway 5xx" });
+try {
+  stepSync(ctx, "payment.charge", () => {
+    from(ctx).warn("retrying payment");
+    recordOutgoingSpan(ctx, "3333333333333333", "payment", "POST /charge");
+    fail(ctx, err);
+    throw err;
+  });
+} catch {
+  setHTTPStatus(ctx, 502);
+}
+
+await finalize(ctx);
+
+console.log(traceId(ctx));

packages/waylog-ts/package.json

@@ -17,6 +17,14 @@
     "./hono": {
       "types": "./dist/hono.d.ts",
       "import": "./dist/hono.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./nest": {
+      "types": "./dist/nest.d.ts",
+      "import": "./dist/nest.js"
     }
   },
   "files": [