feat(lambda): add TypeScript SDK and CDK construct (#909)

* feat(lambda): add TypeScript SDK and CDK construct

Adds the client-side surface on top of the Phase 6a Lambda handler so
adopters can drive a deployed stack from Node without writing AWS-SDK
boilerplate:

- renderToLambda(opts) starts a Step Functions execution and returns a
  handle. Does NOT poll.
- getRenderProgress({ executionArn }) returns a snapshot of progress,
  frames rendered, cost (Lambda GB-seconds + SFN transitions), errors,
  and the final output object once Assemble completes.
- deploySite({ projectDir, bucketName }) content-addresses the project
  tree, tar.gzs it, and uploads to S3 with a HeadObject short-circuit so
  re-renders of the same tree skip the tar+PUT.
- validateDistributedRenderConfig throws a typed InvalidConfigError
  before StartExecution, so shape errors surface synchronously.
- computeRenderCost is exposed for callers who want to format cost out
  of band.

Also ships HyperframesRenderStack, an aws-cdk-lib L2 construct that
emits the same topology as examples/aws-lambda/template.yaml. Lives on
the ./cdk subpath export so SDK-only consumers don't pull aws-cdk-lib
into their runtime graph (declared as an optional peer dependency).

Tests: 24 new unit tests across the SDK plus 9 CDK synth / contract /
snapshot tests. All 83 tests in packages/aws-lambda/src pass.

* refactor(lambda): /simplify pass on the SDK + CDK PR

Pulls shared logic out so the SDK doesn't re-invent things the handler
and the producer already have:

- `formatExtension` extracted to packages/aws-lambda/src/formatExtension.ts.
  handler.ts and renderToLambda.ts both used identical 12-line copies of
  this switch.
- `PLAN_PROJECT_DIR_SKIP_SEGMENTS` is now exported from
  @hyperframes/producer/distributed. deploySite consumes it instead of
  its own duplicate SKIP_TOP_LEVEL set; the two lists were trivially
  identical and would have drifted silently.
- `FakeS3` + `drainBody` factored out of the two SDK test files into
  src/sdk/__fixtures__/fakeS3.ts. Drops ~110 lines of test-file
  duplication and gives future SDK tests a one-line FakeS3 import.
- S3 URI building in deploySite and renderToLambda routes through the
  existing `formatS3Uri` helper instead of inline `s3://...`
  concatenation; matches the convention already in handler.ts.

Net -133 lines across the touched files. All 83 aws-lambda tests still
pass; all 60 producer distributed tests still pass.

* fix(lambda): bump CDK test timeouts for CI cold-start synth

The bun:test default 5s timeout tripped the first CDK snapshot test
in CI when the cold-start `Template.fromStack(stack)` synth took ~5-8s
on the slowest GitHub Actions runner. Locally on a warm shell the
synth measures <1s, so the failure didn't reproduce until PR #909 hit
CI.

Two changes:

  - Both CDK test files cache one synth in `beforeAll(..., 30000)` and
    reuse the result across every test that uses the default props.
    Each individual test now runs in microseconds (pure assertions
    against the already-synthed template), so the 5s timeout no longer
    applies on the hot path.

  - The two contract tests that exercise non-default props
    (reservedConcurrency, projectName) still synth fresh per-test; they
    get a per-test `it(..., 30000)` timeout.

No behavior changes.

* fix(lambda): address PR review on SDK + CDK construct

Three correctness + ergonomics fixes raised in Vai's review:

  - getRenderProgress over-counted SFN transitions by 3-5×. Step
    Functions Standard Workflows bill per state-entry, not per
    history event. Each Task produces ~5-7 history events
    (Scheduled / Started / Succeeded / TaskStateExited / …);
    counting `events.length` reported the runaway. Switch to
    counting `*StateEntered` events explicitly.

  - assembleComplete + outputFile detection was coupled to the
    Lambda payload's `Action` field. Move both signals onto the
    enclosing state name (`StateExited.name === "Assemble"`), which
    is the state-machine identity rather than the Lambda event
    contract. framesRendered increment moves to the same boundary
    (RenderChunk state).

  - SiteHandle now carries `bucketName` directly so README + CLI
    callers don't have to re-parse `projectS3Uri.split("/")[2]`.

Test updates: getRenderProgress tests wrap renderChunk/assemble
events in matching StateEntered + StateExited pairs so the new
state-name-driven dispatch is exercised end-to-end. SiteHandle
fixture in renderToLambda.test.ts gets the new bucketName field.

All 83 aws-lambda tests still pass.

packages/aws-lambda/src/cdk/HyperframesRenderStack.contract.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Contract tests for {@link HyperframesRenderStack}.
+ *
+ * The snapshot test (in this directory's sibling `.snapshot.test.ts`)
+ * guards the full CloudFormation shape. The contract tests below pin
+ * the few properties whose drift would cause a real production
+ * regression — wrong Lambda runtime, lost reserved-concurrency knob,
+ * missing alarms — so we get a high-signal failure independent of
+ * the snapshot.
+ */
+
+import { beforeAll, describe, it } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { App, Stack } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+import { HyperframesRenderStack } from "./HyperframesRenderStack.js";
+
+// CDK synth is slow on cold start (~5-8s on the slowest CI runner). The
+// default bun:test 5s timeout trips the first `it()` that calls it. Cache
+// the default-args synth in `beforeAll` so each test is pure assertions.
+// Tests that need non-default props still synth on demand and bump their
+// own per-test timeout.
+let DEFAULT_TEMPLATE: Template;
+
+function synthFixture(): Template {
+  const zipDir = mkdtempSync(join(tmpdir(), "hf-cdk-test-"));
+  const zipPath = join(zipDir, "handler.zip");
+  writeFileSync(zipPath, "fake zip bytes");
+  const app = new App();
+  const stack = new Stack(app, "TestStack");
+  new HyperframesRenderStack(stack, "Render", { handlerZipPath: zipPath });
+  return Template.fromStack(stack);
+}
+
+describe("HyperframesRenderStack — contract", () => {
+  beforeAll(() => {
+    DEFAULT_TEMPLATE = synthFixture();
+  }, 30000);
+
+  it("provisions exactly one Lambda function on the Node.js 22 runtime, x86_64, 10 GiB /tmp", () => {
+    const t = DEFAULT_TEMPLATE;
+    t.resourceCountIs("AWS::Lambda::Function", 1);
+    t.hasResourceProperties("AWS::Lambda::Function", {
+      Runtime: "nodejs22.x",
+      Architectures: ["x86_64"],
+      EphemeralStorage: { Size: 10240 },
+      MemorySize: 10240,
+      Handler: "handler.handler",
+    });
+  });
+
+  it("provisions exactly one Step Functions state machine of type STANDARD with tracing on", () => {
+    const t = DEFAULT_TEMPLATE;
+    t.resourceCountIs("AWS::StepFunctions::StateMachine", 1);
+    t.hasResourceProperties("AWS::StepFunctions::StateMachine", {
+      StateMachineType: "STANDARD",
+      TracingConfiguration: { Enabled: true },
+    });
+  });
+
+  it("provisions exactly one S3 bucket with PublicAccessBlockConfiguration and a 7-day intermediates lifecycle", () => {
+    const t = DEFAULT_TEMPLATE;
+    t.resourceCountIs("AWS::S3::Bucket", 1);
+    t.hasResourceProperties("AWS::S3::Bucket", {
+      PublicAccessBlockConfiguration: {
+        BlockPublicAcls: true,
+        BlockPublicPolicy: true,
+        IgnorePublicAcls: true,
+        RestrictPublicBuckets: true,
+      },
+      LifecycleConfiguration: {
+        Rules: [
+          {
+            Id: "ExpireIntermediates",
+            Status: "Enabled",
+            Prefix: "renders/",
+            ExpirationInDays: 7,
+          },
+        ],
+      },
+    });
+  });
+
+  it("provisions the three CloudWatch alarms (runaway invocations, Lambda Errors, SFN ExecutionsFailed)", () => {
+    const t = DEFAULT_TEMPLATE;
+    t.resourceCountIs("AWS::CloudWatch::Alarm", 3);
+    t.hasResourceProperties("AWS::CloudWatch::Alarm", {
+      MetricName: "Invocations",
+      Period: 3600,
+      Threshold: 1000,
+    });
+    t.hasResourceProperties("AWS::CloudWatch::Alarm", {
+      MetricName: "Errors",
+      Threshold: 1,
+    });
+    t.hasResourceProperties("AWS::CloudWatch::Alarm", {
+      MetricName: "ExecutionsFailed",
+      Threshold: 1,
+    });
+  });
+
+  // These two synth fresh stacks (non-default props), so they pay the
+  // synth cost individually. Bump per-test timeout so a slow CI runner
+  // doesn't trip the default 5s.
+  it("honours reservedConcurrency when supplied", () => {
+    const zipDir = mkdtempSync(join(tmpdir(), "hf-cdk-test-"));
+    writeFileSync(join(zipDir, "handler.zip"), "fake");
+    const app = new App();
+    const stack = new Stack(app, "TestStack");
+    new HyperframesRenderStack(stack, "Render", {
+      handlerZipPath: join(zipDir, "handler.zip"),
+      reservedConcurrency: 4,
+    });
+    const t = Template.fromStack(stack);
+    t.hasResourceProperties("AWS::Lambda::Function", {
+      ReservedConcurrentExecutions: 4,
+    });
+  }, 30000);
+
+  it("uses the projectName prefix on function + state-machine names", () => {
+    const zipDir = mkdtempSync(join(tmpdir(), "hf-cdk-test-"));
+    writeFileSync(join(zipDir, "handler.zip"), "fake");
+    const app = new App();
+    const stack = new Stack(app, "TestStack");
+    new HyperframesRenderStack(stack, "Render", {
+      handlerZipPath: join(zipDir, "handler.zip"),
+      projectName: "demo",
+    });
+    const t = Template.fromStack(stack);
+    t.hasResourceProperties("AWS::Lambda::Function", { FunctionName: "demo-render" });
+    t.hasResourceProperties("AWS::StepFunctions::StateMachine", {
+      StateMachineName: "demo-render",
+    });
+  }, 30000);
+});