feat(io): opt-out of format-aware parsing for Read/Write (#197)

[KrisSimon]

Migrated from GitLab MR !227 (merged)
feat/197-read-write-raw-qualifier → main
Originally created: 2026-04-06
Merged: 2026-04-08
Author: Kris Simon
Labels: 0.8.2

Summary

Closes #197. ARO-0040's format-aware Read/Write silently misparses files whose extension matches a known format but whose content does not — e.g. a .txt file of plain integers gets run through the key=value parser and binds to [:], then Split fails on _expression_ = [:]. The only workaround was renaming the file to a non-recognised extension.

What changed

Implements Option B from the issue (explicit format qualifier — strict superset of the :raw-only minimum). Resolution order on Read / Write is now:

1. raw (or legacy as String) qualifier → bypass formatting entirely
2. Explicit format qualifier (json, csv, yaml, …) → override extension detection
3. File extension → existing FileFormat.detect(from:)

(* Always returns the raw bytes as a String, no key=value parsing *)
Read the <raw-content: raw> from "./bigfile.txt".
Split the <lines> from <raw-content> by /\n/.

(* Forces JSON parsing even though the extension is .txt *)
Read the <data: json> from "./payload.txt".

(* Writes the string verbatim, no serialisation *)
Write the <log-line: raw> to "./output.txt".

The raw form is also recognised on the URL branches of Read/Write, mirroring the existing as String handling. The legacy as String form continues to work.

Files

• Sources/ARORuntime/FileSystem/FileFormat.swift — new fromQualifier(_:) and isRawQualifier(_:) helpers
• Sources/ARORuntime/Actions/BuiltIn/ExtractAction.swift — Read action (file + URL branches)
• Sources/ARORuntime/Actions/BuiltIn/ResponseActions.swift — Write action
• Examples/FormatAwareIO/main.aro — demonstrates :raw round-trip and forced :json
• Examples/FormatAwareIO/test.hint — asserts the new raw .txt round-trip
• Proposals/ARO-0040-format-aware-io.md — documents the raw qualifier and the updated specifier table

Acceptance criteria

• Read the <x: raw> from "./file.txt". returns the file content as a plain String
• Write the <x: raw> to "./file.txt". writes the string value of <x> without serialisation
• All existing format-aware Read/Write calls without a qualifier are unaffected
• ARO-0040 documentation extended with the raw qualifier and the format-override table
• Examples/FormatAwareIO/ demonstrates :raw

Test plan

• swift build — clean
• Reproduction script: Read the <raw-content: raw> from a .txt file of integers correctly returns the raw string; without :raw the legacy behaviour (empty map) is unchanged
• swift test --filter "Read|Write|Format" — 103 passing, including the existing as String tests
• swift test — 1575/1576 passing; the single failure is the flaky network integration test Write to URL performs POST request ("Connection failed: The network connection was lost"), unrelated to this change
• aro run Examples/FormatAwareIO — full example runs end-to-end and demonstrates both :raw round-trip and forced :json