Debug event reference

The structured debug bus exposes a typed event set for console diagnostics, custom reporters, retained history, and first-party tooling. The protocol is type-only under @vuqs/core/debug-protocol and is governed by DEBUG_PROTOCOL_VERSION rather than the package's normal semver.

Experimental protocol

Event codes and payloads may change when DEBUG_PROTOCOL_VERSION changes. Console prose is a human-facing projection and may improve without changing the protocol version.

For activation, filtering, payload safety, SSR isolation, and reporter examples, start with the debugging guide.

Event shape

Every reporter receives the same envelope:

interface DebugEvent {
  code: string
  scope: string
  level: 'debug' | 'warn'
  seq: number
  timestamp: number
  monotonicTime?: number
  context?: {
    runtimeId?: string
    bindingId?: string
    transactionIds?: readonly number[]
    batchId?: number
  }
  data: unknown
}

The strict KnownDebugEvent union narrows data from code. Import it and the complete DebugEventMap from @vuqs/core/debug-protocol when building protocol-aware tooling.

Summary policies

Visible: produces its own human summary.
Conditional: produces a summary only for the configured outcomes.
Aggregated: contributes to another logical result, such as a committed URL write.
Trace only: stays out of the default summary but appears in the complete trace.
Pass-through: preserves prose and console arguments supplied by createDebugLogger.

A normal write correlates several events but produces one summary result:

text

tx:start → binding:set → gtq:enqueue → gtq:flush
         → adapter:navigate → adapter:commit → gtq:settle

[vuqs] Updated the URL: "color" = "green".

The trace keeps every intermediate event. Its expandable details carry sequence, timestamps, runtime, binding, transaction, batch, scope, and the event's typed payload.

Common summary results

Summary prose describes the observable result of a correlated operation. It does not mirror each low-level event. These are the common committed-write forms:

text

[vuqs] Updated the URL: "color" = "green".
[vuqs] Removed "draft" from the URL.
[vuqs] Updated 2 URL parameters in one navigation: updated "q" and removed "page".
[vuqs] Updated the URL and added a browser history entry: "page" = 2.
[vuqs] "page" now uses its default value (1), so the URL does not need a "page" parameter.

The default-valued form reports the effective query state. It does not imply that the caller explicitly requested a removal. Default canonicalization that leaves the URL unchanged produces no summary line.

Events

The compact index is followed by the full reference grouped by scope. Each entry explains its summary behavior and, when it prints directly, shows an example from the tested console projection. Trace examples use the same formatter as the runtime; dynamic names and counts depend on each payload.

Event	Level	Summary
`binding:created`	`debug`	Trace only
`binding:disposed`	`debug`	Trace only
`binding:set`	`debug`	Aggregated
`engine:clear-on-default`	`debug`	Aggregated
`engine:parse-miss`	`warn`	Visible
`gtq:enqueue`	`debug`	Trace only
`gtq:coalesce`	`debug`	Trace only
`gtq:schedule`	`debug`	Trace only
`gtq:flush`	`debug`	Aggregated
`gtq:flush-skip`	`debug`	Trace only
`gtq:settle`	`debug`	Trace only
`gtq:reset`	`debug`	Trace only
`tx:start`	`debug`	Trace only
`adapter:navigate`	`debug`	Trace only
`adapter:commit`	`debug`	Conditional
`adapter:error`	`warn`	Visible
`adapter:missing`	`debug`	Trace only
`hooks:subscribe`	`debug`	Trace only
`hooks:emit`	`debug`	Trace only
`pipeline:tap`	`debug`	Trace only
`rd:set`	`debug`	Visible
`rd:clear`	`debug`	Visible
`rd:reset`	`debug`	Visible
`rd:register`	`debug`	Trace only
`ctx:build`	`debug`	Trace only
`ctx:switch`	`debug`	Trace only
`ctx:change`	`debug`	Visible
`storage:restore-start`	`debug`	Trace only
`storage:restore`	`debug`	Conditional
`storage:write`	`debug`	Trace only
`storage:coalesce`	`debug`	Trace only
`storage:error`	`warn`	Visible
`serializer:clear-on-default`	`debug`	Trace only
`serializer:build`	`debug`	Trace only
`module:log`	`debug`	Pass-through
`module:warn`	`warn`	Pass-through

binding:createddebug · Trace only
binding:disposeddebug · Trace only
binding:setdebug · Aggregated
engine:clear-on-defaultdebug · Aggregated
engine:parse-misswarn · Visible
gtq:enqueuedebug · Trace only
gtq:coalescedebug · Trace only
gtq:scheduledebug · Trace only
gtq:flushdebug · Aggregated
gtq:flush-skipdebug · Trace only
gtq:settledebug · Trace only
gtq:resetdebug · Trace only
tx:startdebug · Trace only
adapter:navigatedebug · Trace only
adapter:commitdebug · Conditional
adapter:errorwarn · Visible
adapter:missingdebug · Trace only
hooks:subscribedebug · Trace only
hooks:emitdebug · Trace only
pipeline:tapdebug · Trace only
rd:setdebug · Visible
rd:cleardebug · Visible
rd:resetdebug · Visible
rd:registerdebug · Trace only
ctx:builddebug · Trace only
ctx:switchdebug · Trace only
ctx:changedebug · Visible
storage:restore-startdebug · Trace only
storage:restoredebug · Conditional
storage:writedebug · Trace only
storage:coalescedebug · Trace only
storage:errorwarn · Visible
serializer:clear-on-defaultdebug · Trace only
serializer:builddebug · Trace only
module:logdebug · Pass-through
module:warnwarn · Pass-through

`binding` events

`binding:created`

Level: debug
Summary: Trace only
Emitted when: A query binding is created.
Payload: idkeysmanagedPaths

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] binding:created — Created a query binding for "color".

`binding:disposed`

Level: debug
Summary: Trace only
Emitted when: A query binding leaves its Vue effect scope.
Payload: idkeysmanagedPaths

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] binding:disposed — Disposed the query binding for "color".

`binding:set`

Level: debug
Summary: Aggregated
Emitted when: A binding requests a patch or replacement transaction.
Payload: idkeysmanagedPathstouchedtouchedPathsvaluesoptions

Summary behavior: Does not print its own line. It contributes to a later logical result. Contributes the paths requested by this binding to the final committed-write summary.

Trace example

[vuqs trace] binding:set — Requested changes to "color".

`engine` events

`engine:clear-on-default`

Level: debug
Summary: Aggregated
Emitted when: The engine omits a value that equals its resolved default.
Payload: idkeyskeypathsdefaultValue

Summary behavior: Does not print its own line. It contributes to a later logical result. Explains when a changed URL path now uses its resolved default in the final committed-write summary.

Trace example

[vuqs trace] engine:clear-on-default — Omitted "page" from the serialized query because it matches the resolved default value.

`engine:parse-miss`

Level: warn
Summary: Visible
Emitted when: A value present in the URL cannot be decoded by its query param.
Payload: pathraw

Summary behavior: Prints its own line in the default summary. Warns that the invalid URL value was ignored.

Summary example

[vuqs] Ignored an invalid URL value for "page" because it could not be decoded.

Trace example

[vuqs trace] engine:parse-miss — Could not decode the URL value for "page".

`gtq` events

`gtq:enqueue`

Level: debug
Summary: Trace only
Emitted when: Serialized path changes enter the adapter write queue.
Payload: deltaspendingPathCount

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:enqueue — Queued 1 URL change; 2 paths are now pending.

`gtq:coalesce`

Level: debug
Summary: Trace only
Emitted when: Another write joins the current queue batch and its options are merged.
Payload: previousincomingresolvedwriteCount

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:coalesce — Combined another write with the pending URL update.

`gtq:schedule`

Level: debug
Summary: Trace only
Emitted when: The queue schedules its next flush.
Payload: delayMsmechanism

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:schedule — Scheduled the URL update for the next microtask.

`gtq:flush`

Level: debug
Summary: Aggregated
Emitted when: A queue batch materializes the next query and begins navigation.
Payload: pathsqueryoptions

Summary behavior: Does not print its own line. It contributes to a later logical result. Supplies the final changed paths, query, and navigation options to the committed-write summary.

Trace example

[vuqs trace] gtq:flush — Prepared 2 query parameters for navigation.

`gtq:flush-skip`

Level: debug
Summary: Trace only
Emitted when: A scheduled queue flush finds no pending paths.
Payload: reason

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:flush-skip — Skipped the queue flush because no paths were pending.

`gtq:settle`

Level: debug
Summary: Trace only
Emitted when: Committed URL paths are removed from the optimistic overlay.
Payload: dropped

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:settle — Removed committed paths from the optimistic state: "color" and "page".

`gtq:reset`

Level: debug
Summary: Trace only
Emitted when: The adapter write queue is reset.
Payload: None

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] gtq:reset — Reset the URL write queue.

`tx` events

`tx:start`

Level: debug
Summary: Trace only
Emitted when: The adapter runtime assigns an id to a query transaction.
Payload: idmodepathsorigin

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] tx:start — Started a patch transaction for "color".

`adapter` events

`adapter:navigate`

Level: debug
Summary: Trace only
Emitted when: The core or a standalone adapter requests URL navigation.
Payload: adaptermodequery

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] adapter:navigate — Asked the "vue-router" adapter to replace the URL.

`adapter:commit`

Level: debug
Summary: Conditional
Emitted when: The adapter query commits a managed write or changes externally.
Payload: querypathspendingPathCountsource

Summary behavior: Prints only for the outcomes described below. Completes one aggregated vuqs write, or reports paths changed outside vuqs.

Summary example

[vuqs] Updated "color" in the URL.

Trace example

[vuqs trace] adapter:commit — Observed a committed vuqs URL change for "color".

`adapter:error`

Level: warn
Summary: Visible
Emitted when: An adapter navigation throws or rejects.
Payload: adaptererrorrolledBack

Summary behavior: Prints its own line in the default summary. Reports the failed navigation and any values restored by rollback.

Summary example

[vuqs] Could not update the URL; restored the previous value of "color".

Trace example

[vuqs trace] adapter:error — The "vue-router" adapter could not update the URL.

`adapter:missing`

Level: debug
Summary: Trace only
Emitted when: `useQueryAdapter()` finds no adapter in the current injection scope.
Payload: None

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] adapter:missing — No query adapter was available in the current scope.

`hooks` events

`hooks:subscribe`

Level: debug
Summary: Trace only
Emitted when: A module subscribes to a query hook.
Payload: event

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] hooks:subscribe — Subscribed to the "context:change" hook.

`hooks:emit`

Level: debug
Summary: Trace only
Emitted when: A query hook synchronously dispatches to its subscribers.
Payload: eventargs

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] hooks:emit — Emitted the "context:change" hook.

`pipeline` events

`pipeline:tap`

Level: debug
Summary: Trace only
Emitted when: A module registers one or more query pipeline transforms.
Payload: stagesenforce

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] pipeline:tap — Registered a pre transform for the read pipeline.

`rd` events

`rd:set`

Level: debug
Summary: Visible
Emitted when: A runtime-default layer sets one or more values.
Payload: defaults

Summary behavior: Prints its own line in the default summary. Reports the runtime-default decision with a bounded value preview.

Summary example

[vuqs] Set an empty runtime-default layer.

Trace example

[vuqs trace] rd:set — Set runtime defaults for "color" and "page".

`rd:clear`

Level: debug
Summary: Visible
Emitted when: The runtime-default layer is cleared explicitly.
Payload: None

Summary behavior: Prints its own line in the default summary. Reports an explicit removal of the runtime-default layer.

Summary example

[vuqs] Cleared the runtime defaults.

Trace example

[vuqs trace] rd:clear — Cleared the runtime defaults.

`rd:reset`

Level: debug
Summary: Visible
Emitted when: A query context change resets the runtime-default layer.
Payload: context

Summary behavior: Prints its own line in the default summary. Explains that a context change cleared the runtime-default layer.

Summary example

[vuqs] Cleared the runtime defaults after the query context changed to "reviews".

Trace example

[vuqs trace] rd:reset — Cleared runtime defaults after the query context changed to "reviews".

`rd:register`

Level: debug
Summary: Trace only
Emitted when: The runtime-default layer is registered or disposed.
Payload: state

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] rd:register — Registered the runtime-default layer.

`ctx` events

`ctx:build`

Level: debug
Summary: Trace only
Emitted when: The context module builds a query for another context.
Payload: keptdropped

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] ctx:build — Built the query for a context change; kept "search" and dropped "category".

`ctx:switch`

Level: debug
Summary: Trace only
Emitted when: `switchTo()` requests navigation to another query context.
Payload: to

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] ctx:switch — Requested a switch to query context "reviews".

`ctx:change`

Level: debug
Summary: Visible
Emitted when: The active query context changes.
Payload: contextvalidinvalid

Summary behavior: Prints its own line in the default summary. Reports the committed context and any query paths that became invalid.

Summary example

[vuqs] Changed the query context to "reviews"; "category" is no longer valid.

Trace example

[vuqs trace] ctx:change — Changed the query context to "reviews"; "category" is no longer valid.

`storage` events

`storage:restore-start`

Level: debug
Summary: Trace only
Emitted when: The storage module starts its initialization policy.
Payload: keypolicy

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] storage:restore-start — Started restoring "filters" from storage.

`storage:restore`

Level: debug
Summary: Conditional
Emitted when: Storage initialization reaches a terminal outcome.
Payload: keyoutcome

Summary behavior: Prints only for the outcomes described below. Appears only when stored state is applied or the current URL wins over storage.

Summary example

[vuqs] Applied saved query state from "filters".

Trace example

[vuqs trace] storage:restore — Storage initialization for "filters" finished with outcome "restored".

`storage:write`

Level: debug
Summary: Trace only
Emitted when: A storage revision starts saving or removing a snapshot.
Payload: keyrevisionoperationquery

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] storage:write — Started saving revision 3 of "filters" to storage.

`storage:coalesce`

Level: debug
Summary: Trace only
Emitted when: A newer storage revision replaces one that has not started yet.
Payload: keyfromto

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] storage:coalesce — Replaced pending storage revision 2 with revision 3 for "filters".

`storage:error`

Level: warn
Summary: Visible
Emitted when: A storage load, validation, serialization, save, removal, or restore operation fails.
Payload: keyoperationerror

Summary behavior: Prints its own line in the default summary. Reports the failed storage operation with an operation-specific sentence.

Summary example

[vuqs] Could not save "filters" to storage.

Trace example

[vuqs trace] storage:error — Storage operation "save" failed for "filters".

`serializer` events

`serializer:clear-on-default`

Level: debug
Summary: Trace only
Emitted when: The standalone serializer omits a value equal to its default.
Payload: key

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] serializer:clear-on-default — Omitted "page" because it matches its default value.

`serializer:build`

Level: debug
Summary: Trace only
Emitted when: The standalone serializer finishes building a query object.
Payload: query

Summary behavior: Does not appear in the default summary.

Trace example

[vuqs trace] serializer:build — Built a query object with 2 top-level parameters.

`module` events

`module:log`

Level: debug
Summary: Pass-through
Emitted when: A third-party module writes through `createDebugLogger()`.
Payload: namespacemessagevalues

Summary behavior: Prints the message supplied by the module author. Prints the module-authored message and projected native console arguments.

Summary example

[vuqs module] hello

Trace example

[vuqs trace] module:log — Module "module" logged: Resolved value.

`module:warn`

Level: warn
Summary: Pass-through
Emitted when: A third-party module warns through `createDebugLogger()`.
Payload: namespacemessagevalues

Summary behavior: Prints the message supplied by the module author. Prints the module-authored warning and projected native console arguments.

Summary example

[vuqs module] careful

Trace example

[vuqs trace] module:warn — Module "module" warned: Could not resolve value.

Debug event reference ​

Event shape ​

Summary policies ​

Common summary results ​

Events ​

binding events

​binding:created

​binding:disposed

​binding:set

engine events

​engine:clear-on-default

​engine:parse-miss

gtq events

​gtq:enqueue

​gtq:coalesce

​gtq:schedule

​gtq:flush

​gtq:flush-skip

​gtq:settle

​gtq:reset

tx events

​tx:start

adapter events

​adapter:navigate

​adapter:commit

​adapter:error

​adapter:missing

hooks events

​hooks:subscribe

​hooks:emit

pipeline events

​pipeline:tap

rd events

​rd:set

​rd:clear

​rd:reset

​rd:register

ctx events

​ctx:build

​ctx:switch

​ctx:change

storage events

​storage:restore-start

​storage:restore

​storage:write

​storage:coalesce

​storage:error

serializer events

​serializer:clear-on-default

​serializer:build

module events

​module:log

​module:warn

Debug event reference

Event shape

Summary policies

Common summary results

Events

`binding` events

`binding:created`

`binding:disposed`

`binding:set`

`engine` events

`engine:clear-on-default`

`engine:parse-miss`

`gtq` events

`gtq:enqueue`

`gtq:coalesce`

`gtq:schedule`

`gtq:flush`

`gtq:flush-skip`

`gtq:settle`

`gtq:reset`

`tx` events

`tx:start`

`adapter` events

`adapter:navigate`

`adapter:commit`

`adapter:error`

`adapter:missing`

`hooks` events

`hooks:subscribe`

`hooks:emit`

`pipeline` events

`pipeline:tap`

`rd` events

`rd:set`

`rd:clear`

`rd:reset`

`rd:register`

`ctx` events

`ctx:build`

`ctx:switch`

`ctx:change`

`storage` events

`storage:restore-start`

`storage:restore`

`storage:write`

`storage:coalesce`

`storage:error`

`serializer` events

`serializer:clear-on-default`

`serializer:build`

`module` events

`module:log`

`module:warn`