commit 23c51be239f0aaad007c1bf5ded7fa0ad70d3a1f
parent 3f9cccfec9c11af75a625160c87943ceb93e320f
Author: triesap <tyson@radroots.org>
Date: Thu, 11 Jun 2026 17:40:03 -0700
docs: document field event contract
- describe Field workspace, CRDT, file, auth, and NIP-29 event families
- clarify that task, work-session, harvest, and approval records are CRDT document semantics outside rr-rs
- keep Field APIs scoped to public Rust event and codec substrate by default
- validate event, codec, and documentation whitespace checks
Diffstat:
3 files changed, 64 insertions(+), 4 deletions(-)
diff --git a/crates/events/README b/crates/events/README
@@ -6,13 +6,33 @@ models, kinds, and tag conventions for the `radroots` core libraries.
## Overview
* typed content modules for accounts, app data, comments, coops, documents,
- farms, jobs, lists, messages, posts, profiles, reactions, trades, and
- related domains;
+ farms, farm workspaces, farm CRDT changes, farm files, groups, auth events,
+ jobs, lists, messages, posts, profiles, reactions, trades, and related
+ domains;
* shared event references, pointers, and kind and tag definitions used across
event-processing code;
* portable event model semantics for both `std` and `no_std` builds;
* optional integration with `serde` for serialization.
+## Field Event Boundary
+
+`radroots_events` includes the public event-layer models needed by Field-style
+farming operations:
+
+ * workspace manifests for discovering the farm group, relay set, media servers,
+ and supported event kinds;
+ * CRDT change envelopes for operation documents such as tasks, work sessions,
+ harvest records, and approvals;
+ * farm file metadata events for media attached to farm documents;
+ * NIP-42 relay auth and NIP-98 HTTP auth payload models;
+ * NIP-29 group metadata, member lists, roles, invites, joins, leaves, and user
+ operations.
+
+Task records, work sessions, harvest records, approvals, and similar Field
+business objects are CRDT document semantics carried by
+`RadrootsFarmCrdtChange`. They are not separate `rr-rs` event families and this
+crate does not enforce private Field workflow authorization.
+
## Copyright
Except as otherwise noted, all files in the `radroots_events` distribution are
diff --git a/crates/events_codec/README b/crates/events_codec/README
@@ -5,14 +5,38 @@ codecs and tag builders for the `radroots` core libraries.
## Overview
- * canonical decoders for event content, tags, job envelopes, profiles, and
- wire representations;
+ * canonical decoders for event content, tags, job envelopes, profiles, Field
+ event envelopes, NIP-29 group events, and wire representations;
* tag builder helpers for the same event families exposed by
`radroots_events`;
* parsed view and error types for codec-driven validation and routing;
* optional `serde_json` and `radroots_nostr` integration for JSON and wire
interop.
+## Field Event Codecs
+
+The Field codec surface validates the public Nostr event substrate exposed by
+`radroots_events`:
+
+ * workspace manifests use kind `30078`, JSON content, a schema marker, `d` and
+ `h` routing tags, owner tags, relay references, and Field-supported kind
+ declarations;
+ * CRDT changes use kind `78`, JSON content, `h`, `d`, `a`, optional author `p`,
+ and semantic `t` tags, with base64url change payload validation;
+ * farm files use kind `1063`, NIP-94-compatible metadata tags, a workspace
+ address, a farm group id, an owner document tag, lowercase SHA-256 hashes,
+ and optional caption text as content;
+ * NIP-42 relay auth and NIP-98 HTTP auth events require empty content and the
+ auth tags required by their protocols;
+ * NIP-29 group codecs preserve the protocol distinction between `h`-routed
+ group operations and `d`-routed addressable group state.
+
+These codecs validate event shape, routing tags, hashes, and payload encoding.
+They do not validate private Field task, work-session, harvest, approval, or
+authorization semantics; those remain application and CRDT document concerns.
+The companion `radroots_events_codec_wasm` crate exposes deterministic JSON tag
+builders for the same Field and NIP-29 families.
+
## Copyright
Except as otherwise noted, all files in the `radroots_events_codec`
diff --git a/spec/README.md b/spec/README.md
@@ -25,6 +25,22 @@ package.
Public SDK exports are intentionally narrower than the full Rust workspace.
+## Field Event Substrate
+
+Field-oriented farming operations are represented in the public Rust substrate
+through `radroots_events`, `radroots_events_codec`, and
+`radroots_events_codec_wasm`.
+
+The substrate includes workspace manifests, CRDT change envelopes, farm file
+metadata, NIP-42 relay auth, NIP-98 HTTP auth, and NIP-29 group events. These are
+event and codec APIs, not curated SDK operations by default.
+
+Task records, work sessions, harvest records, approvals, and similar Field
+business objects are CRDT document semantics carried inside the CRDT change
+envelope. They are outside the `rr-rs` event-contract boundary unless a future
+contract slice explicitly promotes them into a curated SDK operation surface with
+matching conformance vectors and language export mappings.
+
## Rust Crate Tiers
The public Rust story is tiered explicitly.
