Public release release-98d969b26488

Source commit: 98d969b26488b4cda8b2381fa870276a00ca98ea

Public tree identity: sha256:d02dd1e8d3547a489bb300741bed544bdc60bb8fe0bd541fd43ce9bfa7129a3e

docs/task-abi.md

@@ -0,0 +1,49 @@
+# Task ABI
+
+Clusterflux tasks cross a canonical, versioned Wasm boundary.
+
+## Values
+
+Small arguments and results use canonical JSON-compatible values. Large or
+capability-bearing values use typed handles. A structured boundary value carries
+both its JSON structure and the complete typed handle table required to
+materialize it.
+
+Supported handles include VFS and artifact identities with full tenant, project,
+process, producer, digest, size, and path provenance. The SDK encodes handles as
+explicit placeholders and the runtime replaces only placeholders that match the
+declared type and metadata.
+
+A malformed, missing, extra, cross-scope, or type-mismatched handle fails closed.
+The runtime does not reconstruct authority from a string path or caller-supplied
+display field.
+
+## Tasks
+
+Use the macros and SDK types:
+
+~~~rust
+#[clusterflux::task]
+async fn compile(input: clusterflux::Artifact) -> Result<clusterflux::Artifact, String> {
+    // Task body
+}
+
+#[clusterflux::main]
+async fn build() -> Result<(), String> {
+    // Spawn and join tasks
+}
+~~~
+
+Each spawn produces a TaskSpec containing the logical task instance,
+definition, environment identity and digest, canonical arguments, handles, VFS
+epoch, bundle identity, dispatch ABI, and failure policy.
+
+Use distinct logical task instances when you spawn the same definition twice.
+A restart preserves that logical identity and creates a distinct attempt.
+
+## Failure policy
+
+"FailFast" is the default. "AwaitOperator" leaves the logical join pending after
+failure so you can inspect, accept, cancel, or restart the attempt. Side effects
+outside the VFS boundary are at-least-once across retries; make them idempotent
+or add your own deduplication key.