docs: add filesystem serdes section

Document the FileSystem serdes as a new section in the serialization
reference page. The section covers storage prerequisites (Amazon EFS
and Amazon S3 Files), the createFileSystemSerdes signature and
FileSystemSerdesConfig, storage modes (ALWAYS and OVERFLOW), path
encoding (URI and HASH), the buildPreview helper for inline previews
and PII masking, and how to set the serdes as the handler default with
configureSerdes.

The walkthrough leads with the conservative per-operation StepConfig
pattern. Setting it as the handler default lives in its own subsection.

Coverage is TypeScript only at this stage. Python and Java tabs link to
the parity issues aws-durable-execution-sdk-python#479 and
aws-durable-execution-sdk-java#463.

Verified against packages/aws-durable-execution-sdk-js/src/utils/serdes/
filesystem-serdes.ts and preview.ts at origin/main.

Closes #207

Author: yaythomas

docs/sdk-reference/state/serialization.md

@@ -281,6 +281,230 @@ Map and parallel perations support two SerDes fields that apply at different lev
     --8<-- "examples/java/sdk-reference/serialization/PassThroughSerdesExample.java"
     ```
 
+## FileSystem serdes
+
+The FileSystem serdes stores data on the filesystem and keeps a file pointer in
+the checkpoint. This can be useful when you do not want to store your data in the
+checkpoint itself, for example when your payload exceeds the durable execution
+checkpoint size limit. The persisted value lives on the filesystem and the SDK
+reads it on replay.
+
+The FileSystem serdes requires a filesystem that persists across invocations and
+that every Lambda execution environment can read. In AWS Lambda, this means:
+
+- [Amazon Elastic File System (Amazon EFS)](https://docs.aws.amazon.com/lambda/latest/dg/configuration-filesystem-efs.html).
+    Serverless file system that scales automatically with your workloads.
+- [Amazon S3 Files](https://docs.aws.amazon.com/lambda/latest/dg/configuration-filesystem-s3files.html).
+    Serverless file system for mounting an Amazon S3 bucket. Amazon S3 Files
+    provides access to Amazon S3 objects as files using standard file system
+    operations such as read and write on the local mount path.
+
+!!! warning "Do not use Lambda's `/tmp` directory"
+
+    Lambda's `/tmp` filesystem is local to a single execution environment. A
+    different execution environment may run the next invocation, so the SDK cannot
+    find files written to `/tmp` on replay and deserialization fails. Always mount
+    a durable, shared filesystem.
+
+=== "TypeScript"
+
+    Pass the FileSystem serdes to a single operation through `StepConfig`,
+    `CallbackConfig`, `MapConfig`, or `ParallelConfig`. Other operations in the
+    same handler continue to use the default serdes.
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-walkthrough.ts"
+    ```
+
+=== "Python"
+
+    Coming soon. See
+    [aws-durable-execution-sdk-python#479](https://github.com/aws/aws-durable-execution-sdk-python/issues/479).
+
+=== "Java"
+
+    Coming soon. See
+    [aws-durable-execution-sdk-java#463](https://github.com/aws/aws-durable-execution-sdk-java/issues/463).
+
+### createFileSystemSerdes signature
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-signature.ts"
+    ```
+
+    **Parameters:**
+
+    - `basePath` Directory path where data files are written. Set this to the
+        mount point of your S3 Files or EFS volume.
+    - `config` (optional) `FileSystemSerdesConfig` controlling storage mode, path
+        encoding, and preview generation.
+
+    **Returns:** A `Serdes` that reads and writes JSON files under `basePath`.
+
+=== "Python"
+
+    Coming soon.
+
+=== "Java"
+
+    Coming soon.
+
+### FileSystemSerdesConfig
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-config.ts"
+    ```
+
+    **Fields:**
+
+    - `storageMode` (optional) A `FileSystemSerdesMode` value. Default:
+        `FileSystemSerdesMode.ALWAYS`.
+    - `pathEncoding` (optional) A `FileSystemPathEncoding` value. Default:
+        `FileSystemPathEncoding.URI`.
+    - `generatePreview` (optional) Function that returns a preview object. The SDK
+        stores the preview inline in the checkpoint envelope alongside the file
+        pointer. Use the [`buildPreview`](#preview-and-pii-masking) helper or
+        write your own.
+
+=== "Python"
+
+    Coming soon.
+
+=== "Java"
+
+    Coming soon.
+
+### Storage modes
+
+The `storageMode` enumerated field controls when the SDK writes to the filesystem.
+
+`FileSystemSerdesMode.ALWAYS` writes every value to a file. The checkpoint stores
+only the file pointer.
+
+`FileSystemSerdesMode.OVERFLOW` uses the standard durable execution checkpoint
+store and only writes to the filesystem when the value would exceed the durable
+execution checkpoint size limit.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-overflow.ts"
+    ```
+
+=== "Python"
+
+    Coming soon.
+
+=== "Java"
+
+    Coming soon.
+
+### Path encoding
+
+The `pathEncoding` field controls how the durable execution ARN and the entity ID
+become the on-disk directory and file names.
+
+`FileSystemPathEncoding.URI` builds a per-execution directory from the function
+name, execution name, and invocation ID parsed from the ARN, and encodes the entity
+ID with `encodeURIComponent` for the file name. Names stay readable when you read
+files directly from the mount. A very long entity ID may exceed the filesystem's
+per-name length limit, commonly 255 bytes.
+
+`FileSystemPathEncoding.HASH` replaces the ARN and the entity ID with their SHA-256
+hex digests. Names are a fixed 64 characters and are always filesystem-safe
+regardless of the input characters or length. Choose `HASH` when entity IDs may
+contain characters that are unsafe in a file name, such as `/`, or may be long
+enough to exceed the name-length limit.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-path-encoding.ts"
+    ```
+
+=== "Python"
+
+    Coming soon.
+
+=== "Java"
+
+    Coming soon.
+
+### Preview and PII masking
+
+When the FileSystem serdes writes to a file, the checkpoint envelope only contains
+the file pointer, so the GetDurableExecution API and the AWS Console cannot show
+the actual data for that operation. Configure `generatePreview` to embed a small
+object inline so you can see the data without reading the file.
+
+Use `buildPreview` to compute the preview from a `PreviewConfig`. The config
+selects which fields to include, exclude, or mask. Masking replaces a field's value
+with `***` or a custom string. The preview object is capped at 4096 bytes by
+default.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-preview.ts"
+    ```
+
+    **`PreviewConfig` fields:**
+
+    - `mode` Either `PreviewMode.INCLUDE_ALL` or `PreviewMode.EXCLUDE_ALL`. Sets
+        the starting point before applying `include`, `exclude`, and `mask`.
+    - `include` (optional) Fields to add when starting from `EXCLUDE_ALL`, or to
+        force-include when starting from `INCLUDE_ALL`.
+    - `exclude` (optional) Fields to remove. Always wins over `mask`.
+    - `mask` (optional) Fields whose values become `maskString`. A masked field is
+        visible in the preview unless it is also excluded.
+    - `maskString` (optional) Replacement value for masked fields. Default: `***`.
+    - `maxPreviewBytes` (optional) Maximum size in bytes for the preview object
+        when JSON-serialized. Default: `4096`.
+
+    Each `PreviewField` selector has a `name` and an optional `match`. Use
+    `FieldMatchMode.ANYWHERE` (default) to match the field name at any depth in
+    the object tree, or `FieldMatchMode.PATH` to match an exact dot-notation path
+    from the root.
+
+    Field names that contain a dot are not supported in selectors because a dot is
+    indistinguishable from a path separator. Array structure is not preserved in
+    the output: fields from array elements merge into a plain object at the
+    array's path.
+
+=== "Python"
+
+    Coming soon.
+
+=== "Java"
+
+    Coming soon.
+
+### Set as the default for the handler
+
+When you want every step result, child-context result, invoke result, and
+waitForCondition result in the handler to use the FileSystem serdes, configure it
+once with `configureSerdes`.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/sdk-reference/serialization/filesystem-serdes-default.ts"
+    ```
+
+=== "Python"
+
+    Coming soon. See
+    [aws-durable-execution-sdk-python#479](https://github.com/aws/aws-durable-execution-sdk-python/issues/479).
+
+=== "Java"
+
+    Coming soon. See
+    [aws-durable-execution-sdk-java#463](https://github.com/aws/aws-durable-execution-sdk-java/issues/463).
+
 ## Serialization errors
 
 When serialization or deserialization fails, each SDK raises or throws a specific

examples/typescript/sdk-reference/serialization/filesystem-serdes-config.ts

@@ -0,0 +1,10 @@
+import {
+  FileSystemSerdesMode,
+  FileSystemPathEncoding,
+} from "@aws/durable-execution-sdk-js";
+
+export interface FileSystemSerdesConfig {
+  storageMode?: FileSystemSerdesMode;
+  pathEncoding?: FileSystemPathEncoding;
+  generatePreview?: (value: unknown) => Record<string, unknown> | undefined;
+}

examples/typescript/sdk-reference/serialization/filesystem-serdes-default.ts

@@ -0,0 +1,25 @@
+import {
+  DurableContext,
+  withDurableExecution,
+  createFileSystemSerdes,
+} from "@aws/durable-execution-sdk-js";
+
+export const handler = withDurableExecution(
+  async (event: { customerId: string }, context: DurableContext) => {
+    // Configure once. Every step result, child-context result, invoke result,
+    // and waitForCondition result in this handler is now stored on /mnt/s3.
+    context.configureSerdes({
+      defaultSerdes: createFileSystemSerdes("/mnt/s3"),
+    });
+
+    const profile = await context.step("load-profile", async () => {
+      return loadLargeProfile(event.customerId);
+    });
+
+    return { name: profile.name };
+  },
+);
+
+declare function loadLargeProfile(
+  customerId: string,
+): Promise<{ name: string }>;

examples/typescript/sdk-reference/serialization/filesystem-serdes-overflow.ts

@@ -0,0 +1,10 @@
+import {
+  createFileSystemSerdes,
+  FileSystemSerdesMode,
+} from "@aws/durable-execution-sdk-js";
+
+// Small payloads stay inline in the checkpoint. The SDK only writes to the
+// filesystem when the checkpoint envelope would exceed the size limit.
+export const overflowFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
+  storageMode: FileSystemSerdesMode.OVERFLOW,
+});

examples/typescript/sdk-reference/serialization/filesystem-serdes-path-encoding.ts

@@ -0,0 +1,10 @@
+import {
+  createFileSystemSerdes,
+  FileSystemPathEncoding,
+} from "@aws/durable-execution-sdk-js";
+
+// Hash the ARN and the entity ID into fixed-length, filesystem-safe segments.
+// Use HASH when entity IDs may contain unsafe characters or be very long.
+export const hashedFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
+  pathEncoding: FileSystemPathEncoding.HASH,
+});

examples/typescript/sdk-reference/serialization/filesystem-serdes-preview.ts

@@ -0,0 +1,17 @@
+import {
+  createFileSystemSerdes,
+  buildPreview,
+  PreviewMode,
+} from "@aws/durable-execution-sdk-js";
+
+// The checkpoint envelope stores the file pointer plus a small preview object,
+// so the console can show id and status without reading the full file. The
+// email field is visible but masked, so PII does not land in the checkpoint.
+export const previewFileSystemSerdes = createFileSystemSerdes("/mnt/s3", {
+  generatePreview: (value) =>
+    buildPreview(value, {
+      mode: PreviewMode.EXCLUDE_ALL,
+      include: [{ name: "id" }, { name: "status" }],
+      mask: [{ name: "email" }],
+    }),
+});

examples/typescript/sdk-reference/serialization/filesystem-serdes-signature.ts

@@ -0,0 +1,9 @@
+import {
+  Serdes,
+  FileSystemSerdesConfig,
+} from "@aws/durable-execution-sdk-js";
+
+export type CreateFileSystemSerdes = (
+  basePath: string,
+  config?: FileSystemSerdesConfig,
+) => Serdes<unknown>;

examples/typescript/sdk-reference/serialization/filesystem-serdes-walkthrough.ts

@@ -0,0 +1,25 @@
+import {
+  DurableContext,
+  withDurableExecution,
+  createFileSystemSerdes,
+} from "@aws/durable-execution-sdk-js";
+
+export const handler = withDurableExecution(
+  async (event: { customerId: string }, context: DurableContext) => {
+    const fsSerdes = createFileSystemSerdes("/mnt/s3");
+
+    // Pass the FileSystem serdes to one step. Other operations in this handler
+    // keep using the default JSON serdes.
+    const profile = await context.step(
+      "load-profile",
+      async () => loadLargeProfile(event.customerId),
+      { serdes: fsSerdes },
+    );
+
+    return { name: profile.name };
+  },
+);
+
+declare function loadLargeProfile(
+  customerId: string,
+): Promise<{ name: string }>;