Shared Stream contract proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Evidence
RFC-0020 defines gnomon.subscribe() with a callback and a SubscriptionHandle (open, paused, closed). It does not define Stream<T>. RFC-0026 uses Stream<T> for gRPC input and output, RFC-0027 for GraphQL subscriptions, RFC-0029 for tRPC subscriptions, and RFC-0034 for served streaming operations. RFC-0030 and RFC-0031 also attribute the Stream domain type to RFC-0020. That attribution is unsupported by the authored RFC-0020 and its Lean catalog.
The graph subscription callback receives SubscriptionEvent<T> with event-log metadata. A transport stream yields values of T; it may have a terminal status, client half-close, or protocol-specific acknowledgement. Treating these as the same runtime handle would impose graph event-log semantics on external protocols.
Recommended ownership
Define Stream<T> as a generic typed asynchronous sequence in the core language type contract (RFC-0008, with any execution rules cross-referenced from RFC-0039). T is the per-item type. The shared contract should specify who owns cancellation, end-of-stream, terminal errors, and bounded demand. It should not promise replay, deduplication, or durable delivery. Those guarantees belong to the producer or protocol binding.
Keep RFC-0020’s SubscriptionHandle as the graph query subscription control API. Define an explicit bridge from a graph reactive source to Stream<SubscriptionEvent<T>> for callers that need a stream value. A gRPC, GraphQL, or tRPC adapter can return Stream<T> according to its own transport contract without claiming that every value is an RFC-0020 graph event. Protocol adapters state how cancellation, demand, and terminal errors map to the wire. Client-streaming adapters also define completion of the input side independently of output cancellation.
Acceptance
- A normative source and Lean catalog define the type, item typing, lifecycle, cancellation, completion, errors, and demand behavior.
- RFC-0020 defines the graph source bridge and whether its overflow and acknowledgement rules transfer to the bridge.
- RFC-0026, RFC-0027, RFC-0029, RFC-0030, RFC-0031, and RFC-0034 state their stream direction and protocol-specific behavior without inheriting graph event metadata implicitly.
- Shared RDF
type/Streamnodes point to the normative owner, and generated Turtle and references are regenerated. Source-bound reviews are updated. - Tests cover a finite stream, cancellation, producer error, slow consumer, graph bridge, and gRPC half-close.
Nothing is deployed, so this first-release identity can be corrected without a compatibility migration.