docs(external-storage): shorten the custom-driver excerpt

The whole FileSystemStorageDriver class was too long to read inline. Show
just store and retrieve, which is what the surrounding prose walks through,
and link the sample for the per-payload work in the private helpers:
content-addressed keys, the atomic write, the hash check on read, and the
guard against claims that resolve outside the storage root.

Markers narrowed in samples-typescript to match.

Author: lennessyy

docs/develop/typescript/best-practices/data-handling/external-storage.mdx

@@ -154,180 +154,38 @@ If you need a storage backend other than what the built-in drivers allow, you ca
 Refer to [Choose a storage system](/external-storage#choose-storage) for guidance on selecting a backing store and
 [Lifecycle management](/external-storage#lifecycle) for retention requirements.
 
-The following driver keeps payloads on the filesystem. It comes from the
-[external-storage sample](https://github.com/temporalio/samples-typescript/tree/main/external-storage), which runs it
-end to end and tests it. A shared filesystem works for local development and for Workers that mount the same volume. For
-anything else, use a storage system that every Client and Worker can reach.
+The [external-storage sample](https://github.com/temporalio/samples-typescript/tree/main/external-storage) implements a
+complete driver that keeps payloads on the filesystem, with tests that exercise it end to end. Its `store` and
+`retrieve` methods show the shape every driver has. Each one fans out over the batch it was handed, returns results in
+the order it received them, and passes the SDK's abort signal down so that one failure cancels its siblings:
 
 <!--SNIPSTART typescript-custom-storage-driver -->
 [external-storage/src/filesystem-storage-driver.ts](https://github.com/temporalio/samples-typescript/blob/main/external-storage/src/filesystem-storage-driver.ts)
 ```ts
-export class FileSystemStorageDriver implements StorageDriver {
-  readonly name: string;
-
-  /**
-   * Stable identifier for this *implementation*, shared by every instance and reported
-   * to the server via Worker heartbeat for observability. Distinct from `name`, which
-   * identifies this particular configured instance. The SDK's own drivers use values
-   * like `aws.s3driver` and `gcp.gcsdriver`.
-   */
-  readonly type = 'sample.filesystemdriver';
-
-  private readonly rootDir: string;
-  private readonly maxPayloadSize: number;
-
-  constructor({ rootDir, driverName = 'sample.filesystemdriver', maxPayloadSize }: FileSystemStorageDriverOptions) {
-    this.rootDir = path.resolve(rootDir);
-    this.name = driverName;
-    this.maxPayloadSize = maxPayloadSize ?? DEFAULT_MAX_PAYLOAD_SIZE;
-  }
-
-  /**
-   * Called with every payload the SDK decided to offload, batched per driver. Must
-   * return one claim per payload, in the same order.
-   *
-   * Throwing here fails the enclosing Workflow or Activity Task *retryably*, so a
-   * transient I/O error is retried rather than killing the Execution. That makes it
-   * safe to let errors propagate instead of, say, silently falling back to inline
-   * payloads, which would defeat the point of the size threshold.
-   */
-  async store(context: StorageDriverStoreContext, payloads: Payload[]): Promise<StorageDriverClaim[]> {
-    const keyPrefix = buildKeyPrefix(context.target);
-    return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
-      payloads.map((payload) => this.storePayload(payload, keyPrefix, signal)),
-    );
-  }
-
-  /** Inverse of {@link store}: one payload per claim, in the same order. */
-  async retrieve(context: StorageDriverRetrieveContext, claims: StorageDriverClaim[]): Promise<Payload[]> {
-    return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
-      claims.map((claim) => this.retrievePayload(claim, signal)),
-    );
-  }
-
-  private async storePayload(
-    payload: Payload,
-    keyPrefix: string,
-    abortSignal: AbortSignal,
-  ): Promise<StorageDriverClaim> {
-    // Store the encoded Payload proto, not just `payload.data`. A Payload also carries
-    // metadata (the `encoding` key, protobuf message names, anything a custom
-    // PayloadConverter added), and metadata values are arbitrary bytes that would not
-    // survive a round trip through the string-valued claim map. Encoding the whole
-    // message keeps the payload byte-for-byte identical end to end.
-    const payloadBytes = PayloadProto.encode(payload).finish();
-    if (payloadBytes.length > this.maxPayloadSize) {
-      throw new Error(
-        `Payload of ${payloadBytes.length} bytes exceeds the configured maxPayloadSize of ${this.maxPayloadSize} bytes`,
-      );
-    }
-
-    const hashValue = createHash(HASH_ALGORITHM).update(payloadBytes).digest('hex');
-    const key = `${keyPrefix}/${HASH_ALGORITHM}/${hashValue}`;
-
-    try {
-      await this.writeIfAbsent(key, payloadBytes, abortSignal);
-    } catch (err) {
-      // Wrapping adds the context that makes a retry loop diagnosable: a bare ENOENT
-      // says nothing about which key or which storage root. On ES2022 and above, prefer
-      // `new Error(message, { cause: err })` to keep the original stack attached; these
-      // samples target ES2021, so the message is folded in instead.
-      throw new Error(
-        `FileSystemStorageDriver failed to store [rootDir=${this.rootDir}, key=${key}]: ${describe(err)}`,
-      );
-    }
-
-    // The claim is the only thing that reaches Temporal Server, embedded in the
-    // reference payload that replaces the real one. Keep it small and keep it free of
-    // anything sensitive: it is visible in Workflow History and in the Web UI.
-    //
-    // `rootDir` is deliberately absent. It is deployment configuration, and a second
-    // Worker may well mount the same storage at a different path; putting it in the
-    // claim would pin every historical reference to one machine's filesystem layout.
-    return new StorageDriverClaim({ key, hashAlgorithm: HASH_ALGORITHM, hashValue });
-  }
-
-  /**
-   * Writes the blob unless it is already there. The write goes to a temporary file and
-   * is then renamed, because `rename` is atomic: a reader can only ever observe the
-   * complete blob, never a half-written one. Without that, a crash mid-write would
-   * leave a file whose name promises content it does not contain, and content
-   * addressing would hand it to a reader as valid.
-   */
-  private async writeIfAbsent(key: string, payloadBytes: Uint8Array, abortSignal: AbortSignal): Promise<void> {
-    const filePath = this.resolveKey(key);
-    if (await exists(filePath)) return;
-
-    await mkdir(path.dirname(filePath), { recursive: true });
-    const tempPath = `${filePath}.${randomUUID()}.tmp`;
-    try {
-      await writeFile(tempPath, payloadBytes, { signal: abortSignal });
-      await rename(tempPath, filePath);
-    } catch (err) {
-      await unlink(tempPath).catch(() => undefined);
-      // Two Workers can race to store identical bytes. On POSIX the loser's rename
-      // silently replaces an identical file; on Windows it fails. Either way the blob
-      // is present and correct, so treat that as success.
-      if (await exists(filePath)) return;
-      throw err;
-    }
-  }
-
-  private async retrievePayload(claim: StorageDriverClaim, abortSignal: AbortSignal): Promise<Payload> {
-    const { key, hashAlgorithm, hashValue: expectedHash } = claim.claimData;
-    // Claims come off the wire, so validate rather than assume. A missing field means a
-    // claim written by a different driver, or by an older version of this one.
-    if (!key) {
-      throw new Error("FileSystemStorageDriver claim is missing required field 'key'");
-    }
-    if (hashAlgorithm !== HASH_ALGORITHM || !expectedHash) {
-      throw new Error(
-        `FileSystemStorageDriver claim [key=${key}] must carry hashAlgorithm='${HASH_ALGORITHM}' and a hashValue, ` +
-          `got hashAlgorithm='${hashAlgorithm ?? ''}'`,
-      );
-    }
-
-    const filePath = this.resolveKey(key);
-    let payloadBytes: Uint8Array;
-    try {
-      payloadBytes = await readFile(filePath, { signal: abortSignal });
-    } catch (err) {
-      throw new Error(
-        `FileSystemStorageDriver failed to retrieve [rootDir=${this.rootDir}, key=${key}]: ${describe(err)}`,
-      );
-    }
-
-    // Verifying is cheap next to the read and catches truncation, corruption, and a
-    // claim pointing at the wrong blob. Failing loudly here is much better than
-    // handing malformed bytes to the PayloadConverter, where the error would surface
-    // as a confusing deserialization failure far from its cause.
-    const actualHash = createHash(HASH_ALGORITHM).update(payloadBytes).digest('hex');
-    if (actualHash !== expectedHash) {
-      throw new Error(
-        `FileSystemStorageDriver integrity check failed [key=${key}]: ` +
-          `expected ${HASH_ALGORITHM}:${expectedHash}, got ${HASH_ALGORITHM}:${actualHash}`,
-      );
-    }
-
-    return PayloadProto.decode(payloadBytes);
-  }
-
-  /**
-   * Maps a key to a path under `rootDir`, refusing anything that escapes it. Keys
-   * arrive from Workflow History, which we should not treat as trusted input: a claim
-   * containing `../../etc/passwd` must not turn into a read outside the blob store.
-   */
-  private resolveKey(key: string): string {
-    const filePath = path.resolve(this.rootDir, key);
-    if (filePath !== this.rootDir && !filePath.startsWith(this.rootDir + path.sep)) {
-      throw new Error(`FileSystemStorageDriver refused a key that resolves outside rootDir [key=${key}]`);
-    }
-    return filePath;
-  }
+async store(context: StorageDriverStoreContext, payloads: Payload[]): Promise<StorageDriverClaim[]> {
+  const keyPrefix = buildKeyPrefix(context.target);
+  return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
+    payloads.map((payload) => this.storePayload(payload, keyPrefix, signal)),
+  );
+}
+
+/** Inverse of {@link store}: one payload per claim, in the same order. */
+async retrieve(context: StorageDriverRetrieveContext, claims: StorageDriverClaim[]): Promise<Payload[]> {
+  return runAllAbortingOnFirstError(context.abortSignal, (signal) =>
+    claims.map((claim) => this.retrievePayload(claim, signal)),
+  );
 }
 ```
 <!--SNIPEND-->
 
+The per-payload work happens in the private `storePayload` and `retrievePayload` methods. Read
+[the full driver](https://github.com/temporalio/samples-typescript/blob/main/external-storage/src/filesystem-storage-driver.ts)
+for the parts this page only describes: content-addressed keys, an atomic write, a hash check on read, and a guard that
+rejects claims resolving outside the storage root.
+
+A shared filesystem works for local development and for Workers that mount the same volume. For anything else, use a
+storage system that every Client and Worker can reach.
+
 The following sections walk through the key parts of the driver implementation.
 
 ### 1. Implement the StorageDriver interface
@@ -340,8 +198,7 @@ A custom driver implements the `StorageDriver` interface, which has two readonly
 - `type` is a string that identifies the driver implementation, and the Worker reports it in its heartbeat. Unlike
   `name`, `type` must be the same across all instances of the same driver type regardless of configuration. Two S3
   drivers named `"s3-primary"` and `"s3-archive"` would both report `"aws.s3driver"` as their type, while the built-in
-  GCS driver reports `"gcp.gcsdriver"`. The filesystem driver in the preceding code sample reports
-  `"sample.filesystemdriver"`.
+  GCS driver reports `"gcp.gcsdriver"`. The filesystem driver in the sample reports `"sample.filesystemdriver"`.
 - `store()` receives an array of payloads and returns one `StorageDriverClaim` per payload. A claim wraps a set of
   string key-value pairs that the driver uses to locate the payload later.
 - `retrieve()` receives the claims that `store()` produced and returns the original payloads.