@t4h.framework/fs 0.6.0 → 0.8.0

package/.ai/skills/framework-fs/SKILL.md

@@ -4,6 +4,7 @@ description: >-
   Guides correct use of @t4h.framework/fs in T4H Framework workflows: the
   FileSystemClaim abstraction that the package activities (http, jsx) use to
   read/write files, the Binary result workflows consume, and runtime providers.
+  A workflow never implements Binary itself — see the framework-fs-write skill.
   Use when a workflow orchestrates file-backed package activities, consuming
   Binary results, mocking FileSystemClaim in workflow tests, registering fs
   claim providers, or debugging missing fs provider errors.
@@ -24,10 +25,13 @@ Public exports live in `src/fs.ts`:
 ```typescript
 import {
   FileSystemClaim,
-  // file fan-out / fold — see the framework-fs-split skill
+  // file fan-out / fold / windows — see the framework-fs-split skill
   split, Split, FileSplitActivity, type FileSplitOptions,
-  join, FileJoinActivity, type FileJoinOptions,
-  ByteDelimiterScanner, type FileSplitDelimiter, type ByteRange,
+  join, FileJoinActivity, type FileJoinOptions, type FileJoinWhere,
+  read, FileReadActivity, type FileReadOptions,
+  // turn workflow content into a Binary — see the framework-fs-write skill
+  write, FileWriteActivity, type FileWriteOptions,
+  ByteDelimiterScanner, type FileSplitDelimiter, type ByteRange, type ByteTrim,
 } from '@t4h.framework/fs'
 ```
 
@@ -45,6 +49,7 @@ export abstract class FileSystemClaim {
   public abstract write(
     path: string,
     readable: Readable | Buffer,
+    contentType?: string,
   ): Binary | Promise<Binary>
 
   public abstract read(path: string): Binary | Promise<Binary>
@@ -59,9 +64,9 @@ export abstract class FileSystemClaim {
 
 | Method | Purpose |
 |--------|---------|
-| `write(path, readable)` | Persist stream or buffer at `path`; return a `Binary` handle (metadata + `stream()`). |
+| `write(path, readable, contentType?)` | Persist stream or buffer at `path`; return a `Binary` handle (metadata + `stream()`). When `contentType` is omitted, infer it from the path. |
 | `read(path)` | Load an existing file at `path`; return a `Binary` handle. |
-| `slice(binary, range, encoding?)` | A view over a byte range of an existing binary, **without copying data**. When `encoding` is set, the runtime hydrates the slice as a decoded string instead of a binary — this is how `split` children receive plain strings. |
+| `slice(binary, range, encoding?)` | A view over a byte range of an existing binary, **without copying data**. When `encoding` is set, the runtime hydrates the slice as a decoded string instead of a binary — this is how `split` children receive plain strings. Implementations must **compose ranges**: slicing a slice is relative to it, and the stored range is absolute against the underlying file. |
 
 All methods may return synchronously or as a `Promise`. Implementations choose storage layout; callers should only rely on the returned `Binary` API.
 
@@ -95,6 +100,16 @@ read the resulting `Binary` (e.g. `await res.body.json()` / `text()`). Your only
 responsibility is that the runtime **registers a provider** (below). See
 **Known consumers** for which package primitives to orchestrate.
 
+This package's own workflow-facing primitives are `split`, `join`, `read`
+(small byte windows — headers, trailers — hydrated into the workflow as a
+string, capped at 1 MiB) and `write` (content produced in the workflow turned
+into a file). See the `framework-fs-split` and `framework-fs-write` skills.
+
+**A workflow never implements `Binary`.** Every `Binary` comes from the
+framework — an HTTP response body, `sftp.get`, `write`, `join`. A class holding
+bytes in memory cannot be persisted, and every primitive it is handed to
+persists its input. See the `framework-fs-write` skill.
+
 ---
 
 ## Runtime provider
@@ -117,7 +132,7 @@ These packages depend on `@t4h.framework/fs` and declare `FileSystemClaim`; read
 |---------|--------|
 | `@t4h.framework/http` | The HTTP activity persists response bodies to `fs` and returns them wrapped in a `Body` — you read them with `res.body.json()` / `text()`. |
 | `@t4h.framework/jsx` | Render activities write their output to `fs` and hand back a `Binary` you consume in the workflow. |
-| `@t4h.framework/fs` itself | `FileSplitActivity` persists the durable copy and slices it by ranges; `FileJoinActivity` streams batch results into a new file. See the `framework-fs-split` skill. |
+| `@t4h.framework/fs` itself | `FileSplitActivity` persists the durable copy and slices it by ranges; `FileJoinActivity` streams batch results into a new file; `FileReadActivity` slices (or streams, when the binary is not file-backed) a small window into a string. See the `framework-fs-split` skill. |
 
 Orchestrate these package primitives from your workflow; the `fs` write/read happens inside them.
 
@@ -130,6 +145,9 @@ Test the **workflow** with `TestWorkflowEnvironment` from
 claims the triggered activities need, e.g. `HttpClientRequestClaim` for an HTTP
 call). See the **framework-workflow-testing** skill for the harness API.
 
+Subclassing `Binary` is legitimate **only here**, in a test double standing in
+for the claim — never in workflow or App code.
+
 ```typescript
 import { Readable } from 'node:stream'
 import { Binary } from '@t4h.framework/core'
@@ -175,7 +193,9 @@ Assert `mockWrite` was called with the expected path and body when relevant.
 
 1. **Extend** `FileSystemClaim` from `@t4h.framework/fs`.
 2. **Return** a `Binary` subclass (or core-compatible `Binary`) from `write` and `read` with correct `contentType`, `contentLength`, and `stream()`.
-3. **Accept** `Readable | Buffer` in `write` (match the abstract signature).
+3. **Accept** `Readable | Buffer` and the optional `contentType` in `write`
+   (match the abstract signature), falling back to inferring the content type
+   from the path when it is omitted.
 4. **Register** `{ provide: FileSystemClaim, value: new YourImpl() }` in the runtime (tests use `mockClaim(FileSystemClaim, ...)` instead).
 5. **Keep paths deterministic** when activities replay — unpredictable temp paths are fine if only `Binary` metadata is serialized and replay re-executes `write`; know your serializer/replay story if `path` is persisted.
 
@@ -201,6 +221,7 @@ Assert `mockWrite` was called with the expected path and body when relevant.
 ## Related skills
 
 - `framework-fs-split` — `split`/`join`: fan a file out into a batch of workflows and fold the results back into a file.
+- `framework-fs-write` — `write`: turn workflow content into a `Binary`, and why an App must never implement `Binary`.
 - `framework-core` — `Claim`, `Binary`, and the `TestWorkflowEnvironment` testing harness.
 - `framework-http` — HTTP activities that persist bodies via `FileSystemClaim`.
 - `framework-jsx` — render activities that write/read via `fs`.

package/.ai/skills/framework-fs-split/SKILL.md

@@ -1,20 +1,23 @@
 ---
 name: framework-fs-split
 description: >-
-  Guides correct use of `split` and `join` from @t4h.framework/fs: fanning one
-  large file out into a batch of workflows (one per byte-range slice) and
-  folding the batch results back into a single file — with O(1) parent history
-  and bounded memory regardless of file size. Use whenever a workflow must
-  process a large file record by record — positional files, plain-text lines,
-  NDJSON, batch imports, per-record fan-out with an aggregated output (e.g. a
-  CSV report) — or when the user mentions splitting/chunking a file, running a
-  workflow per line/record, waiting for a batch, collecting batch results, or
-  the symbols `split`, `join`, `Split`, `FileSplitActivity`,
-  `FileJoinActivity`, `WorkflowBatchRef`, `WorkflowBatchClaim`. Prefer this
-  skill over hand-rolling stream loops + `startWorkflow` calls.
+  Guides correct use of `split`, `join` and `read` from @t4h.framework/fs:
+  fanning one large file out into a batch of workflows (one per byte-range
+  slice), folding the batch results back into a single file, and reading small
+  byte windows (headers, trailers) into the workflow — with O(1) parent
+  history and bounded memory regardless of file size. Use whenever a workflow
+  must process a large file record by record — positional files with
+  header/trailer, plain-text lines, NDJSON, batch imports, per-record fan-out
+  with an aggregated output (e.g. a CSV report) — or when the user mentions
+  splitting/chunking a file, trimming a header/trailer, reading a file header,
+  filtering batch results, running a workflow per line/record, waiting for a
+  batch, collecting batch results, or the symbols `split`, `join`, `read`,
+  `Split`, `FileSplitActivity`, `FileJoinActivity`, `FileReadActivity`,
+  `WorkflowBatchRef`, `WorkflowBatchClaim`. Prefer this skill over
+  hand-rolling stream loops + `startWorkflow` calls.
 ---
 
-# `split` / `join` — file fan-out and fold for workflows
+# `split` / `join` / `read` — file fan-out, fold and windows for workflows
 
 `split` turns **one file into a batch of workflows**: it streams the file once,
 cuts it into **byte-range slices** (never copying slice content), starts one
@@ -23,7 +26,7 @@ terminal**. `join` is the inverse: it folds the batch results back into a
 single file, streaming one result at a time.
 
 ```typescript
-import { split, join, Split } from '@t4h.framework/fs'
+import { read, split, join, Split } from '@t4h.framework/fs'
 
 const processRecord = new Workflow(
   { id: 'process-record', schema: Type.String() },
@@ -34,9 +37,13 @@ const processRecord = new Workflow(
 )
 
 const main = new Workflow(fileSchema, async (file: Binary) => {
+  const header = await read(file, { range: { start: 0, end: 240 } })
+  // header: string — recorded in history, never re-read on replay
+
   const batch = await split(file, processRecord, {
     delimiter: Split.char('\n10', { next: 2 }),
-    timeout: 3_600_000,
+    trim: { start: 241, end: 241 }, // header/trailer stay out of the batch
+    timeoutInMs: 3_600_000,
   })
   // this line only runs once the WHOLE batch is terminal;
   // batch: WorkflowBatchRef — { id: string, count: number }
@@ -128,9 +135,10 @@ multi-byte encodings cannot skew the ranges a ranged download will use.
 | Option | Default | Behavior |
 |--------|---------|----------|
 | `every` | `1` | Cut only every N delimiter occurrences — groups N records per child. One million lines with `every: 10_000` start 100 children, each receiving a raw block (inner delimiters untouched) to iterate locally. `keep` arithmetic applies only at actual cut points. |
+| `trim` | none | `{ start?, end? }` **bytes** cut off each end of the file before scanning — a positional header/trailer. Byte-based on purpose: a record-start delimiter (`'\n10'`) fuses the trailer into the last record's slice, so a record-count skip would drop a valid record along with it. Trimmed content never becomes a slice nor counts toward `every`; fetch it with `read`. Positional layouts make the byte counts constants — getting them right is the caller's business. |
 | `skipEmpty` | `true` | Drops zero-length slices (consecutive delimiters, file starting/ending with one) so they never become child workflows. Turn off when slice index must align 1:1 with record position. "Empty" means zero bytes — a whitespace-only line is a regular slice. |
 | `encoding` | `'utf8'` | Converts the delimiter to bytes and tells the runtime how to hydrate each slice for the child (string when set on the slice). |
-| `timeout` | none | Max milliseconds to await the batch; on expiry the activity **rejects** (reason `timeout`) instead of suspending forever — the safety net for a child that never reaches a terminal state. |
+| `timeoutInMs` | none | Max milliseconds to await the batch; on expiry the activity **rejects** (reason `timeout`) instead of suspending forever — the safety net for a child that never reaches a terminal state. |
 
 ---
 
@@ -150,7 +158,7 @@ Formats (content is the **child's** job — the child returns the final line;
 |--------|----------|
 | `lines` | Concatenates raw child outputs, one per line. Options: `header`, `separator` (default `'\n'`). Non-string outputs are JSON-stringified. |
 | `entries` | NDJSON dump of `{ index, status, output }`, one per line — the format-agnostic view of the batch, rejected children included by default. |
-| `csv` | Projects object outputs into RFC 4180 escaped columns. Options: `columns` (required; entries are `{ key, header? }` — `key` selects the value on the child output, `header` labels the header row, plain string is shorthand for `{ key }`), `delimiter` (default `','`), `header` (default `true`). Missing keys become empty cells; nested values are JSON inside the cell. Value *formatting* belongs in the child workflow (sandboxed user code); the join only owns layout. |
+| `csv` | Projects object outputs into RFC 4180 escaped columns. Options: `columns` (required; entries are `{ key, header? }` — `key` selects the value on the child output (a dot-path like `'meta.total'` reaches nested fields, matching the `where` semantics; a literal top-level key with dots wins over the nested path), `header` labels the header row, plain string is shorthand for `{ key }`), `delimiter` (default `','`), `header` (default `true`). Missing keys become empty cells; nested values selected whole are JSON inside the cell. Value *formatting* belongs in the child workflow (sandboxed user code); the join only owns layout. |
 
 **Status filter** (`status?: ('fulfilled' | 'rejected')[]`) selects which
 results make it into the file — there is no error policy. Defaults:
@@ -161,14 +169,92 @@ design; a reprocessing file of failures is one call away:
 const failures = await join(batch, { format: 'entries', status: ['rejected'] })
 ```
 
+**Where filter** (`where?`) narrows results with a **sift (MongoDB-style)
+query** over each entry's output, applied after `status`. Whitelisted subset
+only — declarative, JSON-only operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`,
+`$gte`, `$in`, `$nin`, `$exists`, `$not`, `$and`, `$or`, `$nor`, plus plain
+equality and dot-paths for nested fields. Pass the child output type as a
+generic to narrow top-level keys/values (dot-paths accepted, not narrowed):
+
+```typescript
+const relevant = await join<InvoiceResult>(batch, {
+  format: 'csv',
+  columns: ['id', 'total'],
+  where: { valid: true, total: { $gt: 100 }, 'meta.situacao': 'aprovada' },
+})
+```
+
+Non-serializable filters are rejected eagerly at `toInput` (`TypeError`):
+functions (incl. `$where`), `RegExp` (incl. `$regex`), `undefined`, operators
+outside the subset — a dropped closure would make the replay filter
+differently than the first execution. Arbitrary predicates belong in a custom
+activity in project code (the function then lives in versioned code).
+MongoDB semantics apply: array fields match by containment (`{ tags: 'a' }`
+matches `['a', 'b']`), object values compare deeply, no type coercion. The
+query compiles once and runs inside the existing streaming loop over
+already-hydrated outputs — same memory profile; app-side (decides what enters
+the file, not what leaves the database).
+
+---
+
+## `read`
+
+```typescript
+async function read(
+  binary: Binary,
+  options?: { range?: { start: number; end: number }; encoding?: BufferEncoding },
+): Promise<string>
+```
+
+Reads a byte window of a `Binary` into the workflow as a decoded string. The
+output is recorded in history (replay never re-reads the file), so reads are
+**capped at 1 MiB** — this is the primitive for headers, trailers and single
+records; a data file flows through `split`, never through `read`. `range`
+defaults to the whole binary (same cap applies); `encoding` defaults to
+`'utf8'`.
+
+Two paths under the hood:
+
+1. **Fast path** — `FileSystemClaim.slice`: on a file-backed binary a trailer
+   read is a ranged download, whatever the file size.
+2. **Streaming fallback** — binaries the claim cannot slice (e.g. an SFTP
+   reference): the stream is consumed up to the window and destroyed as soon
+   as it is filled. A header read pulls the first chunks only, whatever the
+   file size; a **trailing window over a non-sliceable binary** is the one
+   expensive case — the stream traverses the whole file to reach it.
+
+Reading a slice is **relative to the slice** (`range: { start: 0, end: 10 }`
+returns its first 10 bytes, not the underlying file's) — slice ranges compose.
+
+The positional-file recipe — header/trailer in the parent, records in the
+batch:
+
+```typescript
+const header = await read(file, { range: { start: 0, end: HEADER } })
+const trailer = await read(file, {
+  range: { start: file.contentLength - TRAILER, end: file.contentLength },
+})
+
+const batch = await split(file, processInvoice, {
+  delimiter: Split.char('\n10', { next: 2 }),
+  trim: { start: HEADER + 1, end: TRAILER + 1 }, // +1: boundary newlines
+})
+
+// e.g. validate the trailer's record count against batch.count
+```
+
 ---
 
 ## Runtime requirements
 
 - Claim providers: `FileSystemClaim` (with `slice`), `WorkflowClaim` (with
   `startMany`), and `WorkflowBatchClaim` (from `@t4h.framework/core`).
-- Production whitelist: `FileSplitActivity`, `FileJoinActivity` and core's
-  `StartManyWorkflowsActivity` must be registered via `runtime.addActivity`.
+- Production whitelist: `FileSplitActivity`, `FileJoinActivity`,
+  `FileReadActivity` and core's `StartManyWorkflowsActivity` must be
+  registered via `runtime.addActivity`.
+- `FileSystemClaim.slice` implementations must **compose ranges** when slicing
+  an already-sliced binary (relative in, absolute against the underlying file
+  out) — `read` and slice consumers rely on that semantics.
 - `FileSplitActivity` is an **AsyncActivity**: the heavy work happens in
   `bootstrap`, executed worker side atomically with the pending suspension —
   children cannot finish before the parent is awaiting them.
@@ -240,6 +326,15 @@ CSV escaping (quotes doubled, delimiter/newline wrapped); the status filter.
   intact (hash it, upload it), pass the `Binary` through.
 - **Forgetting `keep` on positional delimiters.** `Split.char('\n10')` without
   `{ next: 2 }` silently discards the record type code from every slice.
+- **Splitting a positional file without `trim`.** The header rides inside the
+  first slice (with `every: N` it silently consumes a record slot) and the
+  trailer fuses into the last one. Trim both ends; fetch them with `read`.
+- **Reading a data file with `read`.** The output lands in workflow history;
+  the 1 MiB cap is a guard, not a target. Records flow through `split`.
+- **Passing a function as a join filter.** Options serialize into history — a
+  closure cannot survive it, so `toInput` rejects functions, `$where`,
+  `RegExp` and out-of-subset operators with a `TypeError`. Use the `where`
+  sift subset or a custom activity whose predicate lives in versioned code.
 - **Hand-rolling the loop.** A stream-and-`startWorkflow` loop inside an
   activity re-parses on replay, misses the barrier, and pushes N entries into
   history.

package/.ai/skills/framework-fs-write/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: framework-fs-write
+description: >-
+  Guides the use of `write` from @t4h.framework/fs — the only supported way to
+  turn content produced inside a workflow (a JSON string, a CSV, a positional
+  return file, a Buffer) into a `Binary` that other primitives accept. Use
+  whenever a workflow must upload, send or save content it built itself:
+  `sftp.put`/`sftp.append` with generated content, an HTTP request carrying a
+  file, persisting a report, or when the user mentions creating/building a
+  Binary, converting a string or Buffer to a Binary, "stringToBinary",
+  "BufferBinary", or hits `Unsupported binary instance`. A workflow must NEVER
+  implement its own `Binary` subclass — this skill explains why and what to do
+  instead.
+---
+
+# `write` — turn workflow content into a `Binary`
+
+Every file primitive in the framework speaks `Binary`: `sftp.put`,
+`sftp.append`, `split`, `join`, `pdf`, HTTP bodies. A `Binary` is a
+**reference** to stored content, not the bytes themselves.
+
+`write` is what produces one from content your workflow built:
+
+```typescript
+import { write } from '@t4h.framework/fs'
+
+const file = await write(JSON.stringify(state, null, 2), {
+  contentType: 'application/json',
+})
+
+await sftp.put('/out/state.json', file)
+```
+
+Package path: `framework/packages/fs`. Import only from the package root.
+
+---
+
+## Never implement `Binary` yourself
+
+This is the rule this skill exists to enforce:
+
+```typescript
+// ❌ NEVER — this class cannot be persisted
+class BufferBinary extends Binary {
+  constructor(
+    private readonly content: Buffer,
+    readonly contentType = '...',
+  ) {
+    super()
+  }
+
+  get contentLength() {
+    return this.content.length
+  }
+
+  stream() {
+    return Readable.from(this.content)
+  }
+}
+
+await sftp.put('/out/state.json', new BufferBinary(Buffer.from(json)))
+```
+
+```typescript
+// ✅ ALWAYS
+await sftp.put(
+  '/out/state.json',
+  await write(json, {
+    contentType: 'application/json',
+  }),
+)
+```
+
+### Why a custom `Binary` cannot work
+
+A workflow is **durable**: the body replays, and each activity is persisted
+before it runs. When you pass a value to a primitive, that value becomes the
+activity **input**, and the input is serialized to storage.
+
+A `Binary` holding bytes in memory has nothing to serialize into — the buffer
+lives in the process that built it, and the activity may run in another
+process, minutes later, after a replay. The runtime therefore has to spool the
+content somewhere before the activity can be persisted at all.
+
+Symptoms of doing it by hand:
+
+- `TypeError: Unsupported binary instance` when the activity input is
+  serialized, on older runtimes;
+- the activity is never persisted, the transaction rolls back, and the message
+  ends up in the dead letter queue after the retries — the run stops mid-way
+  with no obvious error in the workflow itself;
+- it may still "work" locally, because the dev server keeps values in memory
+  and never crosses a process boundary. **Passing locally proves nothing here.**
+
+Current runtimes spool an unknown `Binary` to storage instead of failing, so a
+hand-rolled class may survive — but it pays a hidden copy, loses the content
+type you meant to set, and depends on runtime-version behavior. `write` is the
+contract.
+
+---
+
+## API
+
+```typescript
+function write(
+  content: string | Buffer,
+  options?: FileWriteOptions,
+): Promise<Binary>
+```
+
+| Option        | Type             | Required | Purpose                                                                                                                                                     |
+| ------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contentType` | `string`         | No       | Content type stored with the file — `'application/json'`, `'text/csv'`, … Defaults to what the filename extension implies, then `application/octet-stream`. |
+| `filename`    | `string`         | No       | Name the file is stored under. Defaults to the activity id.                                                                                                 |
+| `encoding`    | `BufferEncoding` | No       | How a **string** `content` is encoded. Defaults to `'utf8'`. Ignored for a `Buffer`, which always travels as base64.                                        |
+
+`write` is a durable activity: on replay the content is **not** written again;
+the recorded `Binary` is returned.
+
+---
+
+## When to use it
+
+| Situation                                                                     | Use                                             |
+| ----------------------------------------------------------------------------- | ----------------------------------------------- |
+| Send content the workflow built (JSON, CSV, positional file) over SFTP/HTTP   | `write`                                         |
+| Read a small window of an existing file into the workflow                     | [`read`](./read) — see **framework-fs-split**   |
+| Fan a large file out into one workflow per record                             | `split` — see **framework-fs-split**            |
+| Fold a finished batch back into a file                                        | `join` — see **framework-fs-split**             |
+| Content already is a `Binary` (HTTP response body, `sftp.get`, `join` result) | pass it straight through — do not re-`write` it |
+
+---
+
+## Size matters: keep content bounded
+
+`write` takes content **in workflow memory**, so it is bounded by what the
+workflow can reasonably hold — a state file, a report, a return file. It is not
+the tool for gigabyte outputs.
+
+To build a large file out of many records, use `join` over a batch: it streams
+results one at a time into storage, and nothing but the resulting `Binary`
+reaches the workflow.
+
+---
+
+## Patterns
+
+### A) Write then upload
+
+```typescript
+const csv = await write(rows.map(toCsvLine).join('\n'), {
+  contentType: 'text/csv',
+  filename: `report-${input.date}.csv`,
+})
+
+await sftp.put(`/out/report-${input.date}.csv`, csv)
+```
+
+### B) Write once, use twice
+
+The same `Binary` can be handed to more than one primitive — it is a reference,
+so nothing is copied and nothing is re-uploaded:
+
+```typescript
+const file = await write(json, { contentType: 'application/json' })
+
+await sftp.put(`${path}.tmp`, file)
+await sftp.put(path, file)
+```
+
+Note that a hand-rolled `Binary` backed by a single-use stream would break on
+the second call — another reason not to build one.
+
+### C) Binary content
+
+```typescript
+const pdfBytes: Buffer = await buildPdf()
+
+await sftp.put(
+  '/out/invoice.pdf',
+  await write(pdfBytes, {
+    contentType: 'application/pdf',
+  }),
+)
+```
+
+---
+
+## Testing
+
+`write` goes through `FileSystemClaim.write`, so mock that claim like any
+other. See the **framework-workflow-testing** skill for the harness API.
+
+```typescript
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { FileSystemClaim } from '@t4h.framework/fs'
+
+// replay runs the workflow twice — return a fresh Binary per call
+const write = vi
+  .fn()
+  .mockImplementation(
+    async (path, content, contentType) =>
+      new MockBinary(
+        Buffer.isBuffer(content) ? content : await toBuffer(content),
+        contentType,
+      ),
+  )
+
+await env.execute(workflow, input, {
+  claims: [
+    mockClaim(FileSystemClaim, { write, read: vi.fn(), slice: vi.fn() }),
+  ],
+})
+
+expect(write).toHaveBeenCalledWith('report.csv', expect.any(Buffer), 'text/csv')
+```
+
+---
+
+## Anti-patterns
+
+- **Declaring a class that extends `Binary`** in an App. There is no valid
+  reason to; use `write`.
+- Helper functions like `stringToBinary(value)` that wrap content in a custom
+  class — replace the implementation with `write`, keeping the helper name if
+  it reads well.
+- `write`-ing a value that already is a `Binary` (an HTTP response body, a
+  `sftp.get` result, a `join` output) — that copies a file to obtain a
+  reference you already had.
+- Building a large file by concatenating records in memory and calling `write`
+  once — use `split`/`join` instead.
+- Relying on the filename extension to set the content type when the consumer
+  cares about it — pass `contentType` explicitly.
+
+---
+
+## Related skills
+
+- `framework-fs` — the `FileSystemClaim` contract and runtime providers.
+- `framework-fs-split` — `read`/`split`/`join`: windows, fan-out and fold.
+- `framework-sftp` — `sftp.put`/`append`, the most common consumer of `write`.
+- `framework-workflow-creation` — the rules a workflow body must follow.

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# @t4h.framework/fs
+
+## 0.8.0
+
+### Minor Changes
+
+- [`8c56f76`](https://github.com/tech4humans-brasil/framework/commit/8c56f7697390a1ea966d1e91ff5f35ce5751a0d7) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - feat: write in-memory content to durable storage from a workflow
+
+  There was no supported way to turn a string or a Buffer into a `Binary` inside
+  a workflow — every `Binary` came from an existing file (`http` response,
+  `sftp.get`, `split`, `join`). Anyone needing to upload computed content had to
+  implement `Binary` by hand, and such an instance can never be persisted, so the
+  activity carrying it failed to serialize.
+
+  `write(content, options?)` covers that gap: it pushes an activity that stores
+  the content through the `FileSystemClaim` and returns a `Binary` that survives
+  replay.
+
+  ```ts
+  const file = await write(JSON.stringify(data), {
+    contentType: 'application/json',
+  })
+
+  await sftp.put('/out/data.json', file)
+  ```
+
+  `FileSystemClaim.write` takes an optional `contentType` — until now the content
+  type was always inferred from the file extension.
+
+  The dev codec no longer diverges from the runtime one: its binary kind used to
+  match only `DevFileBinary`, so a hand-written `Binary` was silently serialized
+  as a plain object locally and blew up once deployed. It now matches any
+  `Binary` and spools unknown ones to disk, the same way the runtime spools them
+  to the file storage.
+
+- [`8c56f76`](https://github.com/tech4humans-brasil/framework/commit/8c56f7697390a1ea966d1e91ff5f35ce5751a0d7) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - Adds FS write activity
+
+## 0.7.0
+
+### Minor Changes
+
+- Adds support to read file ([#109](https://github.com/tech4humans-brasil/framework/pull/109))
+
+## 0.6.0
+
+### Minor Changes
+
+- Adds activity to split and join binary ([#100](https://github.com/tech4humans-brasil/framework/pull/100))
+
+## 0.5.0
+
+### Patch Changes
+
+- Update skills ([`6d7e7bc`](https://github.com/tech4humans-brasil/framework/commit/6d7e7bca0c780a9c53a0c9e5aa0a865c5af67959))
+
+## 0.4.0
+
+### Patch Changes
+
+- Internal dependency updates
+
+## 0.3.0
+
+### Minor Changes
+
+- Adds fs package ([`538c9bd`](https://github.com/tech4humans-brasil/framework/commit/538c9bd5c49031ceb94ef8d6c513f6ffc9c848c5))
+- Adds support to buffer in fs write package ([`476f9f0`](https://github.com/tech4humans-brasil/framework/commit/476f9f08a7b379a3361e42f8577078462276210b))
+- Adds .ai/skills in packages ([#88](https://github.com/tech4humans-brasil/framework/pull/88))
+
+### Patch Changes
+
+- Remove activity prefix from file system claim class name ([`d257bd1`](https://github.com/tech4humans-brasil/framework/commit/d257bd177d477a56a897ba862a0be1f50531c633))
+- Adds github workflow to run, build, tests and lint ([#18](https://github.com/tech4humans-brasil/framework/pull/18))
+- Adds readme ([`3a55794`](https://github.com/tech4humans-brasil/framework/commit/3a557942769fa022b9a39504046d22b0083e734f))
+- Update package metadata and author information across multiple packages ([`2ca73df`](https://github.com/tech4humans-brasil/framework/commit/2ca73df42dc63c86ed44717b50d5402fca45b4e7))
+- Improve repository info ([`1fad92d`](https://github.com/tech4humans-brasil/framework/commit/1fad92d959b804189fd1486d047115995ac81eb0))
+- Fix resolve module resolution issues in check-types ([`c97a0d2`](https://github.com/tech4humans-brasil/framework/commit/c97a0d2747f38e561cc5c7d592b20de0459bc1ee))
+- Update package dependencies across multiple packages ([`8b4fc1d`](https://github.com/tech4humans-brasil/framework/commit/8b4fc1d0e92d6bd880ddf4c8119fb68c49c53760))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tech for humans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.