From 2b9180b661d1d39db6bdcbe3ff4025fbb0515e2d Mon Sep 17 00:00:00 2001 From: CleverThis Date: Mon, 13 Apr 2026 01:04:23 +0000 Subject: [PATCH] =?UTF-8?q?docs(spec):=20clarify=20resource=20event=20type?= =?UTF-8?q?s=20=E2=80=94=20add=20RESOURCE=5FCREATED,=20RESOURCE=5FDELETED,?= =?UTF-8?q?=20RESOURCE=5FMOVED?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specification.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/specification.md b/docs/specification.md index f0803345d..b1de5b128 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -46039,7 +46039,10 @@ CleverAgents emits domain events for every significant state change. Events flow # Resource events RESOURCE_ACCESSED = "resource.accessed" + RESOURCE_CREATED = "resource.created" RESOURCE_MODIFIED = "resource.modified" + RESOURCE_DELETED = "resource.deleted" + RESOURCE_MOVED = "resource.moved" RESOURCE_INDEXED = "resource.indexed" # Correction events @@ -46136,6 +46139,37 @@ CleverAgents emits domain events for every significant state change. Events flow return self._subject +#### Resource Event Types and ResourceFileWatcher Behavior + +> **Clarification added in response to issue [#8018](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8018).** +> Tracked for implementation in [#8025](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8025). + +The full set of resource `EventType` values is: + +| `EventType` member | String value | Description | +|---|---|---| +| `RESOURCE_ACCESSED` | `"resource.accessed"` | A resource was read or queried. | +| `RESOURCE_CREATED` | `"resource.created"` | A new resource file was created on disk. | +| `RESOURCE_MODIFIED` | `"resource.modified"` | An existing resource file was modified in place. | +| `RESOURCE_DELETED` | `"resource.deleted"` | A resource file was removed from disk. | +| `RESOURCE_MOVED` | `"resource.moved"` | A resource file was renamed or relocated. | +| `RESOURCE_INDEXED` | `"resource.indexed"` | A resource was (re-)indexed into the context store. | + +**`ResourceFileWatcher` mapping (required behavior):** + +`ResourceFileWatcher` monitors the filesystem using a `FileChangeType` enumeration produced by the underlying watcher library. It **MUST** map each `FileChangeType` to a distinct `EventType` as follows: + +| `FileChangeType` | Required `EventType` emitted | +|---|---| +| `CREATED` | `RESOURCE_CREATED` | +| `MODIFIED` | `RESOURCE_MODIFIED` | +| `DELETED` | `RESOURCE_DELETED` | +| `MOVED` | `RESOURCE_MOVED` | + +**Design rationale:** The `EventType` value alone MUST be sufficient for any subscriber to determine the nature of a filesystem change. Subscribers MUST NOT need to inspect `details["change_type"]` or any other payload field to distinguish between created, modified, deleted, or moved events. Encoding the change semantics in the event type (rather than a payload field) keeps subscriber logic simple and enables type-safe subscription via `EventBus.subscribe(EventType.RESOURCE_DELETED, handler)`. + +> **Historical note:** Prior to this clarification, `ResourceFileWatcher` emitted `RESOURCE_MODIFIED` for all filesystem change types (created, modified, deleted, moved) and included a `change_type` key in `details` so subscribers could distinguish them. This was a workaround for the missing enum variants and is **no longer the intended design**. New and updated implementations MUST use the distinct event types listed above. + #### LLM Call Tracing Every LLM invocation is traced with full context for debugging and cost tracking: -- 2.52.0