gnomonlearn
Docs/RFC-0020/Reference catalog

RFC-0020 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0020: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0020.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0020. Edit that source and regenerate this catalog.


Title: Reactive Query and Subscription Model
Status: draft
Owners: Platform, Runtime
Diagnostic range: M20000-M20999

Proof citations in source: 4 / 4. Standalone proof verification is pending.


Definitions

(none defined)

Diagnostics

CodeSeverityDescription
M20003WarningEvent dropped due to pending queue overflow (drop-oldest or drop-newest policy).
M20004ErrorSubscription closed due to pending queue overflow (error policy).
M20005ErrorSubscription query references entity kind outside principal’s read scope; subscription rejected.
M20006ErrorAgent subscription read scope exceeds declared permissions; subscription rejected.
M20007WarningEvent log cursor was lost; subscription resumed from approximate position.
M20008Warningpause() called on a closed subscription; ignored.
M20009ErrorstartFrom event ID not found in event log; subscription cannot resume from that position.

Invariants

  1. A closed subscription cannot be reopened; a new subscription must be created. (enforced by: runtime)
  2. Any event lost to queue overflow must produce a diagnostic; silent loss is forbidden. (enforced by: runtime)
  3. Effective delivery scope intersects the scope fixed at open with current grants; revocations narrow it and later grants require a new subscription. (enforced by: runtime)
  4. Events for a single entity are always delivered in sequenceNumber order regardless of event-log batch ordering. (enforced by: runtime)
  5. Every committed event matching the subscription query and effective read scope must be delivered at least once to an open, non-overflowed subscription. (enforced by: runtime)
  6. The runtime tracks the last 10,000 acknowledged eventIds per subscription; rejected callbacks remain eligible for retry and in-flight IDs are tracked separately. (enforced by: runtime)
  7. The subscription query cannot be changed after open; changing it requires close and reopen. (enforced by: runtime)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Delivery Semantics

  1. MUST — Consumers MUST be idempotent with respect to eventId.
  2. SHOULD — Consumers SHOULD implement their own idempotency checks for events older than the deduplication window.
  3. MUST — Events for the same entityId MUST be delivered in sequenceNumber order.
  4. MUST_NOT — The runtime MUST NOT deliver event N+1 for an entity until event N has been acknowledged.
  5. MUST — The runtime MUST add an eventId to the 10,000-ID completed deduplication window only after callback acknowledgement; it MUST track in-flight IDs separately and keep rejected callbacks eligible for retry.
  6. MUST — The runtime MUST deliver every event matching the subscription query and effective read scope at least once while the subscription is open and non-overflowed; queue overflow MUST emit M20003 or M20004 before loss.

Failure Modes

  1. SHOULD — On lost event log cursor, the runtime SHOULD resume from the last acknowledged eventId if startFrom is provided; otherwise reopen from now.

Goals

  1. MUST — Back-pressure MUST be explicit: a slow subscriber MUST receive a defined overflow signal rather than silent event loss.
  2. MUST — Events MUST be delivered in emission order within a single entity.
  3. MUST — Every committed event matching the subscription query and effective read scope MUST eventually be delivered to an open, non-overflowed subscription; queue overflow MUST emit M20003 or M20004 before loss.
  4. MUST — Subscription lifecycle transitions MUST be deterministic and observable for debugging.
  5. MUST — The API MUST enforce readScope constraints at subscription open and at each delivery boundary; out-of-scope events MUST be silently filtered.
  6. MUST — The subscription API MUST be a pure overlay on the RFC-0007 query model and introduce no new storage concepts.

Invariants

  1. MUST — An event lost due to queue overflow MUST produce a diagnostic; silent event loss is not permitted. (proof citation: rfc0020_b8_grounded; verification pending)
  2. MUST — Effective delivery scope is the intersection of the subscription scope fixed at open and the principal’s current grants; revocations narrow delivery and later grants require a new subscription.
  3. MUST — Every committed event matching the subscription query and effective read scope MUST be delivered at least once to an open, non-overflowed subscription.
  4. MUST — Once closed, a subscription cannot be reopened; the subscription query is immutable after open.
  5. MUST — The runtime MUST enforce intra-entity sequenceNumber ordering regardless of event log batch ordering.

Security: Read-Scope Enforcement

  1. MUST_NOT — An agent subscription MUST NOT widen its read scope beyond what is declared in the agent’s permissions block. (proof citation: rfc0020_b21_grounded; verification pending)
  2. MUST — At subscription open time, the runtime MUST verify the principal has read access to the entity kinds in the subscription query. (proof citation: rfc0020_b13_grounded; verification pending)
  3. MUST — If the subscription query references entity kinds outside the principal’s read scope, the subscription MUST be rejected at open time with M20005. (proof citation: rfc0020_b11_grounded; verification pending)

Linked References

(no cross-RFC dependencies)