@@ -0,0 +1,11 @@
+---
+'@objectstack/service-knowledge': patch
+---
+
+fix(service-knowledge): the realtime event bridge no longer keeps a `record.created` / `record.updated` / `record.deleted` branch, and its docs name the events ObjectQL really publishes (#20573)
+
+No producer emits a bare `record.*` event: the ObjectQL engine publishes `data.record.created` / `data.record.updated` / `data.record.deleted` for a single-record write and `data.records.updated` / `data.records.deleted` for a predicate write (`multi: true`), and `@objectstack/spec` already dropped the bare names from `RealtimeEventType`. The `KnowledgeServicePlugin` subscription handler still carried a branch for them, with a `payload.record ?? payload` fallback for a shape nothing sends. That branch is removed. The `data.record.*` sync (record body from `after`, id from `recordId`) and the `data.records.*` stale-index warning are unchanged.
+
+The `enableEventSync` option's TSDoc and the `handleRecordUpsert` / `handleRecordDelete` docs now name `data.record.created|updated|deleted` instead of `record.*`.
+
+If a plugin of yours publishes a bare `record.created`, `record.updated` or `record.deleted` event through `IRealtimeService` and relied on the knowledge index following it, publish `data.record.created|updated|deleted` with the `DataEvent` payload instead (the record in `after`, its id in `recordId`).
@@ -168,3 +168,66 @@ describe('#4626 — KnowledgeServicePlugin event sync on data.record.*', () => {
     expect(message).toContain('application-level predicate writes are not');
   });
 });
+
+/**
+ * No producer emits a bare `record.created|updated|deleted` event: the ObjectQL
+ * engine publishes `data.record.*` (and `data.records.*` for a predicate
+ * write), and the spec's `RealtimeEventType` no longer contains the bare names.
+ * The bridge therefore has no branch for them — and no `payload.record ??
+ * payload` fallback to read a record out of a shape nothing sends. Each case
+ * delivers the legacy shape and then the same record as `data.record.*` on the
+ * SAME subscription: the legacy delivery must sync nothing while the
+ * `data.record.*` one does, so a silent harness cannot pass for a removed branch.
+ */
+describe('a bare record.* event is not part of the sync vocabulary', () => {
+  const ROW = { id: 'task_1', title: 'Ship it', notes: 'the record body' };
+  const at = '2026-08-02T12:00:00.000Z';
+  const legacy = (type: string, payload: Record<string, unknown>): RealtimeEventPayload => ({
+    type,
+    object: 'task',
+    payload,
+    timestamp: at,
+  });
+
+  it.each([
+    ['record.created', 'under payload.record', { record: ROW }],
+    ['record.updated', 'as the payload itself', ROW],
+  ])('%s (%s) upserts nothing, while data.record.created upserts the same row', async (type, _shape, payload) => {
+    const harness = makeCtx();
+    const { service, deliver } = await harness.boot(new KnowledgeServicePlugin());
+    const upsert = vi.spyOn(service, 'handleRecordUpsert').mockResolvedValue(undefined);
+    const del = vi.spyOn(service, 'handleRecordDelete').mockResolvedValue(undefined);
+
+    await deliver(legacy(type, payload));
+
+    expect(upsert).not.toHaveBeenCalled();
+    expect(del).not.toHaveBeenCalled();
+
+    // Control: same subscription, same row, the name the engine publishes.
+    await deliver(CREATED);
+
+    expect(upsert).toHaveBeenCalledTimes(1);
+    expect(upsert).toHaveBeenCalledWith('task', ROW);
+  });
+
+  it.each([
+    ['payload.id', { id: 'task_1' }],
+    ['payload.record.id', { record: { id: 'task_1' } }],
+  ])('record.deleted (id from %s) deletes nothing, while data.record.deleted deletes the same id', async (_shape, payload) => {
+    const harness = makeCtx();
+    const { service, deliver } = await harness.boot(new KnowledgeServicePlugin());
+    const upsert = vi.spyOn(service, 'handleRecordUpsert').mockResolvedValue(undefined);
+    const del = vi.spyOn(service, 'handleRecordDelete').mockResolvedValue(undefined);
+
+    await deliver(legacy('record.deleted', payload));
+
+    expect(upsert).not.toHaveBeenCalled();
+    expect(del).not.toHaveBeenCalled();
+
+    // Control: same subscription, same id, the name the engine publishes.
+    await deliver(DELETED);
+
+    expect(del).toHaveBeenCalledTimes(1);
+    expect(del).toHaveBeenCalledWith('task', 'task_1');
+  });
+});
@@ -21,10 +21,14 @@ export interface KnowledgeServicePluginOptions {
    */
   sources?: KnowledgeSource[];
   /**
-   * Subscribe to ObjectQL `record.*` events from `IRealtimeService`
-   * for `object` sources. Defaults to `true`. Set to `false` to
-   * disable inline event sync (e.g. when an external indexer drives
-   * upserts).
+   * Subscribe to ObjectQL `data.record.created` / `data.record.updated` /
+   * `data.record.deleted` events from `IRealtimeService` for `object`
+   * sources. Defaults to `true`. Set to `false` to disable inline event
+   * sync (e.g. when an external indexer drives upserts).
+   *
+   * The aggregate `data.records.updated` / `data.records.deleted` events a
+   * predicate write (`multi: true`) publishes carry a count, not records:
+   * they cannot be synced and only log a warning that the index may be stale.
    * @default true
    */
   enableEventSync?: boolean;
@@ -159,12 +163,18 @@ export class KnowledgeServicePlugin implements Plugin {
 
         // [#4626] `data.record.*` payloads ARE the spec's `DataEvent`
         // (`@objectstack/spec/api`): the record body lives in `after`, the id
-        // in the required top-level `recordId`. Reading the payload itself as
-        // a record (what the shared branch below did) indexed the ENVELOPE —
-        // `{ recordId, after }` — as if it were the row, so object sources
-        // were syncing documents with none of the record's fields, and a
-        // delete never resolved an id at all. Kept separate from the legacy
-        // `record.*` shape rather than merged behind fallbacks.
+        // in the required top-level `recordId`. The payload itself is the
+        // ENVELOPE, never the row — reading it as a record indexes
+        // `{ recordId, after }` as if it were the row (a document with none of
+        // the record's fields), and a delete never resolves an id at all.
+        //
+        // These three are the only per-record names the ObjectQL engine
+        // publishes. There is deliberately no `record.created|updated|deleted`
+        // branch: no producer emits those names (the spec's `RealtimeEventType`
+        // dropped them for the same reason), so a branch for them is dead code
+        // plus a `payload.record ?? payload` fallback for a shape nobody sends.
+        // An event type this handler does not name — those, and `metadata.*`
+        // too — falls through without a sync.
         if (type === 'data.record.created' || type === 'data.record.updated') {
           const record = payload.after as Record<string, unknown> | undefined;
           if (record && typeof record === 'object') {
@@ -214,21 +224,6 @@ export class KnowledgeServicePlugin implements Plugin {
           );
           return;
         }
-
-        if (type === 'record.created' || type === 'record.updated') {
-          const record =
-            (payload.record as Record<string, unknown> | undefined) ?? payload;
-          if (record && typeof record === 'object') {
-            await service.handleRecordUpsert(object, record as Record<string, unknown>);
-          }
-          return;
-        }
-        if (type === 'record.deleted') {
-          const recordObj = payload.record as Record<string, unknown> | undefined;
-          const id =
-            (payload.id as string | undefined) ?? (recordObj?.id as string | undefined);
-          if (id) await service.handleRecordDelete(object, id);
-        }
       });
       ctx.logger.info?.('KnowledgeServicePlugin: event sync subscription active.');
     });
 
@@ -229,9 +229,10 @@ export class KnowledgeService implements IKnowledgeService {
   // ── Sync entrypoints (called by the host plugin's event bridge) ───
 
   /**
-   * Apply an ObjectQL `record.created` / `record.updated` event to
-   * every `object` source bound to the matching object. Failures are
-   * logged but never thrown — sync must not block writes.
+   * Apply an ObjectQL `data.record.created` / `data.record.updated` event
+   * (the record body is the event payload's `after`) to every `object`
+   * source bound to the matching object. Failures are logged but never
+   * thrown — sync must not block writes.
    */
   async handleRecordUpsert(object: string, record: Record<string, unknown>): Promise<void> {
     const targets = this.sourcesForObject(object);
@@ -249,7 +250,7 @@ export class KnowledgeService implements IKnowledgeService {
     }
   }
 
-  /** Apply an ObjectQL `record.deleted` event. */
+  /** Apply an ObjectQL `data.record.deleted` event (the id is the payload's `recordId`). */
   async handleRecordDelete(object: string, recordId: string): Promise<void> {
     const targets = this.sourcesForObject(object);
     for (const source of targets) {