@cosmicdrift/kumiko-framework 0.2.3 → 0.3.0

package/src/engine/__tests__/pipeline-observability.integration.ts

@@ -0,0 +1,142 @@
+// Pipeline-engine observability integration test.
+//
+// Verifies that step.run sees a working ctx.tracer + ctx.metrics —
+// not the noop provider — and that any spans/metrics emitted inside
+// a step land in the same recording provider that the dispatcher
+// uses for its own spans.
+//
+// Why this is a prod-readiness check, not a "nice-to-have": handlers
+// without observability are invisible in prod. The dispatcher already
+// emits a `write.handler` span around every handler invocation; the
+// pipeline-runner runs INSIDE that span. If the pipeline-runner
+// accidentally substituted a noop tracer (or stripped the ctx field),
+// every step inside a pipeline-form handler would be untraceable —
+// and we wouldn't notice until a prod incident lacks the breadcrumbs.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { createRecordingProvider, type RecordingProvider } from "../../testing";
+import { defineFeature } from "../define-feature";
+import { defineWriteHandler } from "../define-handler";
+import { createEntity, createTextField } from "../factories";
+import { pipeline } from "../pipeline";
+
+// Handler whose step bodies emit a span + a metric. The recording
+// provider afterwards lets us assert both landed.
+const observedSchema = z.object({});
+
+const observedHandler = defineWriteHandler({
+  name: "observed",
+  schema: observedSchema,
+  access: { roles: ["Admin"] },
+  perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+    r.step.compute("traced", (ctx) => {
+      // Span emitted from inside a step. End it explicitly because
+      // step.run is sync-or-async-but-not-otel-instrumented; the
+      // recording provider only persists spans on .end().
+      const span = ctx.tracer.startSpan("test:step.compute.traced");
+      span.end();
+      return null;
+    }),
+    r.step.compute("metered", (ctx) => {
+      // Note: MetricsHandle.inc is (name, labels?, value?) — labels comes
+      // BEFORE value. Argument order trips a lot of authors; the engine-
+      // wide convention follows the OpenTelemetry meter shape.
+      ctx.metrics.inc("test_step_counter_total", { step_name: "metered" }, 1);
+      return null;
+    }),
+    r.step.return({ isSuccess: true as const, data: { ok: true } }),
+  ]),
+});
+
+const obsEntity = createEntity({
+  table: "obs_smoke_things",
+  fields: { label: createTextField({ required: true }) },
+});
+
+const obsFeature = defineFeature("obstest", (r) => {
+  r.entity("obs-thing", obsEntity);
+  // Pre-register the counter the step body emits — feature-scoped
+  // metric names get a `kumiko_<feature>_` prefix at boot.
+  r.metric("test_step_counter_total", {
+    type: "counter",
+    labels: ["step_name"],
+  });
+  r.writeHandler(observedHandler);
+});
+
+let stack: TestStack;
+let provider: RecordingProvider;
+
+beforeAll(async () => {
+  provider = createRecordingProvider();
+  stack = await setupTestStack({
+    features: [obsFeature],
+    systemHooks: [],
+    observability: provider,
+  });
+  await unsafeCreateEntityTable(stack.db, obsEntity, "obs-thing");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  provider.reset();
+  await stack.redis.flushNamespace();
+});
+
+describe("pipeline-engine observability inheritance", () => {
+  test("ctx.tracer.startSpan inside a step is recorded by the dispatcher's provider", async () => {
+    await stack.http.writeOk("obstest:write:observed", {}, TestUsers.admin);
+
+    const stepSpans = provider.spansByName("test:step.compute.traced");
+    expect(stepSpans).toHaveLength(1);
+
+    // Sanity: the dispatcher's own span exists too — confirms the
+    // step-span isn't somehow replacing it.
+    const writeHandlerSpans = provider.spans.filter((s) => s.name.includes("handler"));
+    expect(writeHandlerSpans.length).toBeGreaterThan(0);
+  });
+
+  test("ctx.metrics.inc inside a step lands in the dispatcher's metric stream", async () => {
+    await stack.http.writeOk("obstest:write:observed", {}, TestUsers.admin);
+
+    // Feature-scoped metric names get a `kumiko_<feature>_` prefix at boot.
+    const stepMetrics = provider.metricEvents.filter(
+      (m) => m.name === "kumiko_obstest_test_step_counter_total",
+    );
+    expect(stepMetrics).toHaveLength(1);
+    expect(stepMetrics[0]).toMatchObject({
+      type: "counter.inc",
+      name: "kumiko_obstest_test_step_counter_total",
+      value: 1,
+      labels: { step_name: "metered" },
+    });
+  });
+
+  test("step-emitted spans are explicit children of the dispatcher's handler span", async () => {
+    // Trace-correlation: a span emitted from inside step.run must
+    // belong to the same trace as the dispatcher's outer handler
+    // span AND be a child of it (parentSpanId resolves to a span
+    // whose name contains "handler"). The earlier weaker assertion
+    // (sameTrace.length > 1) would have passed even if a future
+    // regression gave step-spans a fresh traceId — multiple spans
+    // in the same trace can be coincidence.
+    await stack.http.writeOk("obstest:write:observed", {}, TestUsers.admin);
+
+    const stepSpan = provider.spansByName("test:step.compute.traced")[0];
+    expect(stepSpan).toBeDefined();
+    expect(stepSpan!.parentSpanId).toBeDefined();
+
+    // Resolve the parent span explicitly — it must exist within the
+    // same trace AND name a handler-related concept.
+    const parent = provider
+      .spansByTraceId(stepSpan!.traceId)
+      .find((s) => s.spanId === stepSpan!.parentSpanId);
+    expect(parent).toBeDefined();
+    expect(parent!.name).toMatch(/handler/);
+  });
+});

package/src/engine/__tests__/pipeline-performance.integration.ts

@@ -0,0 +1,152 @@
+// Pipeline-engine performance smoke-test.
+//
+// Compares the M.1 pipeline-form handler ({ perform: pipeline(...) })
+// against the equivalent free-form handler ({ handler: async (...) })
+// over N identical writes against the real Postgres stack. The point
+// is NOT to optimise — the pipeline-form is a thin wrapper, not a
+// hot-path engine. The point is to lock in a baseline so a future
+// regression (e.g. an O(N²) walkAllSteps refactor) shows up as a
+// visible delta rather than as silently-degraded latency.
+//
+// Bar: pipeline-form mean+p95 latency must stay within 3× free-form.
+// Anything beyond that is either a real perf bug or a load-flake worth
+// inspecting. The test logs the actual numbers (bun test stdout) so
+// the baseline is visible in CI without re-running locally.
+//
+// Scope caveat: this measures dispatcher + handler-form combined over
+// a SINGLE-step handler (just r.step.return). The dispatcher dominates
+// the wall-time, which is what makes the bar useful — a real per-step
+// regression would have to be massive to show up. To isolate per-step
+// overhead specifically, you'd want a 5+-step handler so the per-step
+// cost has room to accumulate. Out of scope for the M.1 prod-ready
+// gate; if a future regression suspect needs that breakdown, extend
+// here with a longer-pipeline handler variant.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "vitest";
+import { z } from "zod";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { defineWriteHandler } from "../define-handler";
+import { createEntity, createNumberField, createTextField } from "../factories";
+import { pipeline } from "../pipeline";
+
+// Same logical operation in both handler-forms: read input, return a
+// trivial transformed payload. No DB-write — the goal is to compare
+// the handler-invocation pipeline overhead, not Postgres write latency
+// (the latter would dominate any real-world handler comparison and
+// hide whatever overhead the step-engine adds).
+const trivialSchema = z.object({ n: z.number() });
+
+const trivialPipeline = defineWriteHandler({
+  name: "trivial:pipeline",
+  schema: trivialSchema,
+  access: { roles: ["Admin"] },
+  perform: pipeline<{ n: number }, { doubled: number }>(({ event, r }) => [
+    r.step.return(() => ({
+      isSuccess: true as const,
+      data: { doubled: event.payload.n * 2 },
+    })),
+  ]),
+});
+
+const trivialFreeform = defineWriteHandler({
+  name: "trivial:freeform",
+  schema: trivialSchema,
+  access: { roles: ["Admin"] },
+  handler: async (event) => ({
+    isSuccess: true as const,
+    data: { doubled: event.payload.n * 2 },
+  }),
+});
+
+const productEntity = createEntity({
+  table: "perf_smoke_products",
+  fields: {
+    sku: createTextField({ required: true }),
+    qty: createNumberField({ default: 0 }),
+  },
+});
+
+const perfFeature = defineFeature("perftest", (r) => {
+  // Entity-registration is needed so the dispatcher boots cleanly even
+  // though the trivial handlers don't touch it; without an entity, the
+  // feature is empty enough that some boot-validators short-circuit.
+  r.entity("perf-product", productEntity);
+  r.writeHandler(trivialPipeline);
+  r.writeHandler(trivialFreeform);
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [perfFeature], systemHooks: [] });
+  await unsafeCreateEntityTable(stack.db, productEntity, "perf-product");
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await stack.redis.flushNamespace();
+});
+
+// Sample size: 100 calls per form keeps the test under ~5s even on a
+// loaded laptop. Higher N gives tighter percentiles but costs wall-time
+// in CI. The signal we need (within-3× ratio) shows up at N=100.
+const N = 100;
+
+async function timeMany(call: () => Promise<unknown>): Promise<number[]> {
+  const samples: number[] = [];
+  for (let i = 0; i < N; i++) {
+    const start = performance.now();
+    await call();
+    samples.push(performance.now() - start);
+  }
+  return samples;
+}
+
+function summarise(samples: number[]): { mean: number; p50: number; p95: number } {
+  const sorted = [...samples].sort((a, b) => a - b);
+  const mean = sorted.reduce((acc, v) => acc + v, 0) / sorted.length;
+  const p50Idx = Math.floor(sorted.length * 0.5);
+  const p95Idx = Math.floor(sorted.length * 0.95);
+  // Non-null: sorted has length N (≥1) and indices are clamped < N.
+  const p50 = sorted[p50Idx]!;
+  const p95 = sorted[p95Idx]!;
+  return { mean, p50, p95 };
+}
+
+describe("pipeline-engine performance smoke-test", () => {
+  test(`pipeline-form latency stays within 3× free-form (N=${N})`, async () => {
+    // Warmup: 10 calls per form to amortise JIT + Postgres connection-
+    // pool warmup, otherwise the first samples dominate the percentiles.
+    for (let i = 0; i < 10; i++) {
+      await stack.http.writeOk("perftest:write:trivial:pipeline", { n: i }, TestUsers.admin);
+      await stack.http.writeOk("perftest:write:trivial:freeform", { n: i }, TestUsers.admin);
+    }
+
+    const pipelineSamples = await timeMany(() =>
+      stack.http.writeOk("perftest:write:trivial:pipeline", { n: 1 }, TestUsers.admin),
+    );
+    const freeformSamples = await timeMany(() =>
+      stack.http.writeOk("perftest:write:trivial:freeform", { n: 1 }, TestUsers.admin),
+    );
+
+    const pipelineStats = summarise(pipelineSamples);
+    const freeformStats = summarise(freeformSamples);
+
+    // eslint-disable-next-line no-console -- observable baseline for CI logs
+    console.log(
+      `[perf] pipeline mean=${pipelineStats.mean.toFixed(2)}ms p50=${pipelineStats.p50.toFixed(2)}ms p95=${pipelineStats.p95.toFixed(2)}ms | ` +
+        `freeform mean=${freeformStats.mean.toFixed(2)}ms p50=${freeformStats.p50.toFixed(2)}ms p95=${freeformStats.p95.toFixed(2)}ms | ` +
+        `ratio mean=${(pipelineStats.mean / freeformStats.mean).toFixed(2)}× p95=${(pipelineStats.p95 / freeformStats.p95).toFixed(2)}×`,
+    );
+
+    // Assert: the pipeline-form must not be more than 3× slower than
+    // free-form on the mean. Higher → suspect a real perf regression.
+    // p95-ratio is logged but NOT asserted — tail-latency on a loaded
+    // CI runner is too noisy for a hard threshold.
+    expect(pipelineStats.mean).toBeLessThan(freeformStats.mean * 3);
+  });
+});

package/src/engine/__tests__/pipeline-sub-pipelines.test.ts

@@ -0,0 +1,288 @@
+// Sub-pipeline step-builders — branch + forEach.
+//
+// Both consume static StepInstance arrays as sub-pipelines (Q11) and
+// share the build-time `validateNoReturnSteps` guard (Q12 — extracted
+// to steps/_no-return-guard.ts). Tests cover happy paths, scope
+// hygiene, error-propagation and build-time guards.
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { TestUsers } from "../../stack";
+import { defineWriteHandler } from "../define-handler";
+import { pipeline } from "../pipeline";
+import { buildBranchStep } from "../steps/branch";
+import { buildForEachStep } from "../steps/for-each";
+import { buildReturnStep } from "../steps/return";
+import { buildMinimalCtx } from "./_pipeline-test-utils";
+
+describe("r.step.branch", () => {
+  it("runs the `onTrue` array when the condition is truthy and writes propagate to outer steps", async () => {
+    const handlerDef = defineWriteHandler({
+      name: "demo:branch-then",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { value: number }>(({ r }) => [
+        r.step.branch({
+          if: () => true,
+          onTrue: [r.step.compute("inThen", () => 42)],
+          onFalse: [r.step.compute("inElse", () => -1)],
+        }),
+        r.step.return(({ steps }) => ({
+          isSuccess: true as const,
+          data: { value: (steps["inThen"] as number | undefined) ?? 0 },
+        })),
+      ]),
+    });
+
+    const result = await handlerDef.handler(
+      { type: "demo:branch-then", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) expect(result.data).toEqual({ value: 42 });
+  });
+
+  it("runs the `onFalse` array when the condition is falsy", async () => {
+    const handlerDef = defineWriteHandler({
+      name: "demo:branch-else",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { value: number }>(({ r }) => [
+        r.step.branch({
+          if: () => false,
+          onTrue: [r.step.compute("inThen", () => 42)],
+          onFalse: [r.step.compute("inElse", () => 99)],
+        }),
+        r.step.return(({ steps }) => ({
+          isSuccess: true as const,
+          data: { value: (steps["inElse"] as number | undefined) ?? 0 },
+        })),
+      ]),
+    });
+
+    const result = await handlerDef.handler(
+      { type: "demo:branch-else", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    if (result.isSuccess) expect(result.data).toEqual({ value: 99 });
+  });
+
+  it("is a no-op when the condition is falsy and `onFalse` is omitted", async () => {
+    const handlerDef = defineWriteHandler({
+      name: "demo:branch-noop",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { ran: boolean }>(({ r }) => [
+        r.step.branch({
+          if: () => false,
+          onTrue: [r.step.compute("ran", () => true)],
+          // no onFalse
+        }),
+        r.step.return(({ steps }) => ({
+          isSuccess: true as const,
+          data: { ran: (steps["ran"] as boolean | undefined) ?? false },
+        })),
+      ]),
+    });
+
+    const result = await handlerDef.handler(
+      { type: "demo:branch-noop", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    if (result.isSuccess) expect(result.data).toEqual({ ran: false });
+  });
+
+  it("rejects r.step.return inside `onTrue` at build time (Q12 guard)", () => {
+    expect(() =>
+      buildBranchStep({
+        if: () => true,
+        onTrue: [buildReturnStep(() => ({ isSuccess: true as const, data: { x: 1 } }))],
+      }),
+    ).toThrow(/r\.step\.return is not allowed inside r\.step\.branch\.onTrue/);
+  });
+
+  it("rejects r.step.return inside `onFalse` at build time (Q12 guard)", () => {
+    expect(() =>
+      buildBranchStep({
+        if: () => true,
+        onTrue: [],
+        onFalse: [buildReturnStep(() => ({ isSuccess: true as const, data: { x: 1 } }))],
+      }),
+    ).toThrow(/r\.step\.return is not allowed inside r\.step\.branch\.onFalse/);
+  });
+});
+
+describe("r.step.forEach", () => {
+  it("iterates the sub-pipeline once per item with scope[as] set", async () => {
+    // Sub-pipeline reads scope[as] via a compute step that pushes
+    // each iteration into a side-array. The side-array is the test
+    // observable — proves the scope-key is set per-iteration.
+    const observed: number[] = [];
+    const handlerDef = defineWriteHandler({
+      name: "demo:foreach",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+        r.step.forEach({
+          over: () => [10, 20, 30],
+          as: "n",
+          do: [
+            r.step.compute("recorded", ({ scope }) => {
+              observed.push(scope["n"] as number);
+              return scope["n"];
+            }),
+          ],
+        }),
+        r.step.return({ isSuccess: true as const, data: { ok: true } }),
+      ]),
+    });
+
+    await handlerDef.handler(
+      { type: "demo:foreach", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    expect(observed).toEqual([10, 20, 30]);
+  });
+
+  it("restores the prior scope-value (or deletes the key) after the loop", async () => {
+    // Verifies forEach's scope-key isn't leaking after the loop by
+    // inspecting steps from a downstream step. The contract: scope
+    // is forEach-local — keys set inside don't survive past it.
+    let scopeKeyAfter: unknown = "INITIAL";
+    const handlerDef = defineWriteHandler({
+      name: "demo:foreach-cleanup",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+        r.step.forEach({
+          over: () => [1],
+          as: "tmp",
+          do: [r.step.compute("noop", () => null)],
+        }),
+        r.step.compute("after", ({ scope }) => {
+          scopeKeyAfter = scope["tmp"];
+          return null;
+        }),
+        r.step.return({ isSuccess: true as const, data: { ok: true } }),
+      ]),
+    });
+
+    await handlerDef.handler(
+      { type: "demo:foreach-cleanup", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    expect(scopeKeyAfter).toBeUndefined();
+  });
+
+  it("is a no-op for an empty array", async () => {
+    let bodyRan = false;
+    const handlerDef = defineWriteHandler({
+      name: "demo:foreach-empty",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+        r.step.forEach({
+          over: () => [],
+          as: "n",
+          do: [
+            r.step.compute("ranOnce", () => {
+              bodyRan = true;
+              return null;
+            }),
+          ],
+        }),
+        r.step.return({ isSuccess: true as const, data: { ok: true } }),
+      ]),
+    });
+
+    await handlerDef.handler(
+      { type: "demo:foreach-empty", payload: {}, user: TestUsers.admin },
+      buildMinimalCtx(),
+    );
+    expect(bodyRan).toBe(false);
+  });
+
+  it("rejects r.step.return inside `do` at build time (Q12 guard)", () => {
+    expect(() =>
+      buildForEachStep({
+        over: () => [],
+        as: "x",
+        do: [buildReturnStep(() => ({ isSuccess: true as const, data: {} }))],
+      }),
+    ).toThrow(/r\.step\.return is not allowed inside r\.step\.forEach\.do/);
+  });
+
+  it("rejects unsupported concurrency at build time (Q16: only 1 in M.1.6)", () => {
+    // Cast (not @ts-expect-error) so the test stays valid when Q16
+    // expands the type to accept N>1 — at that point this test should
+    // delete or move under a Followup #12 build-validator suite, not
+    // silently break for unrelated reasons.
+    expect(() =>
+      buildForEachStep({
+        over: () => [],
+        as: "x",
+        do: [],
+        concurrency: 5 as 1,
+      }),
+    ).toThrow(/concurrency=5 not supported in M\.1\.6/);
+  });
+
+  it("propagates a thrown error from a sub-step (try/finally restores scope)", async () => {
+    let postForEachRan = false;
+    const handlerDef = defineWriteHandler({
+      name: "demo:foreach-throws",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, never>(({ r }) => [
+        r.step.forEach({
+          over: () => [1, 2, 3],
+          as: "item",
+          do: [
+            r.step.compute("check", ({ scope }) => {
+              if (scope["item"] === 2) throw new Error("item-2-bang");
+              return null;
+            }),
+          ],
+        }),
+        r.step.compute("after", () => {
+          postForEachRan = true;
+          return null;
+        }),
+        r.step.return({ isSuccess: true as const, data: undefined as never }),
+      ]),
+    });
+
+    await expect(
+      handlerDef.handler(
+        { type: "demo:foreach-throws", payload: {}, user: TestUsers.admin },
+        buildMinimalCtx(),
+      ),
+    ).rejects.toThrow(/item-2-bang/);
+    expect(postForEachRan).toBe(false);
+  });
+
+  it("throws when the over-resolver returns a non-array at runtime", async () => {
+    const handlerDef = defineWriteHandler({
+      name: "demo:foreach-bad-over",
+      schema: z.object({}),
+      access: { roles: ["User"] },
+      perform: pipeline<Record<string, never>, { ok: true }>(({ r }) => [
+        r.step.forEach({
+          // Cast: TypeScript would normally catch this; the test exercises
+          // the runtime guard for hand-crafted / dynamically built cases.
+          over: (() => "not an array") as unknown as () => readonly never[],
+          as: "x",
+          do: [],
+        }),
+        r.step.return({ isSuccess: true as const, data: { ok: true } }),
+      ]),
+    });
+
+    await expect(
+      handlerDef.handler(
+        { type: "demo:foreach-bad-over", payload: {}, user: TestUsers.admin },
+        buildMinimalCtx(),
+      ),
+    ).rejects.toThrow(/'over' resolver must return an array/);
+  });
+});

package/src/engine/__tests__/raw-table.test.ts

@@ -56,10 +56,10 @@ describe("r.rawTable — declaration", () => {
       });
     });
     expect(feature.rawTables).toHaveProperty("cache");
-    expect(feature.rawTables.cache?.reason).toBe(
+    expect(feature.rawTables["cache"]?.reason).toBe(
       "external Stripe webhook cache, write-only by webhook handler",
     );
-    expect(feature.rawTables.cache?.table).toBe(probeTable);
+    expect(feature.rawTables["cache"]?.table).toBe(probeTable);
   });
 });