vapor-chamber API reference - v1.16.0
    Preparing search index...

    Type Alias CommandMeta

    Automatic metadata stamped on every command.

    type CommandMeta = {
        ts: number;
        id: string;
        causationId?: string;
        correlationId?: string;
        idempotencyKey?: string;
        origin?: "user" | "remote" | "sync" | "replay" | "agent" | string & {};
    }
    Index
    ts id causationId? correlationId? idempotencyKey? origin?
    ts: number

    Wall-clock stamp for correlation and audit — NOT a timing instrument.

    Read from Date.now() once per microtask turn and shared by every command dispatched inside that turn. The first command of each turn carries an exact stamp; the 2nd..nth of the same synchronous run repeat it. Since Date.now() is millisecond-resolution and a typical burst is sub-millisecond, those commands would almost always have received the same number anyway — what is actually given up is intra-burst resolution in bursts long enough to cross a millisecond (a thousand-command rehydrate reads as instantaneous). Bought ~15-25ns per dispatch; measured in tests/clock-source-ab.test.ts.

    Ordering does not depend on this field. meta.id is a monotonic counter and stays unique and ordered — use it, not ts, to sequence commands.

    Do not measure durations with it, cached or not. Date.now() is wall clock: millisecond-resolution and not monotonic, so an NTP correction or a clock change can move it, backwards included. That was true before this cache and is not a consequence of it. For real timing use performance.now() in a plugin; on a hot loop use createFastLane(), which stamps no meta at all.

    Note this is a wall clock, not an ordering key: two commands in the same millisecond share a ts. For order use meta.id, whose default generator is a monotonic counter. To stamp an exact time, do it in a plugin — see the note above _configureClock.

    id: string

    Unique command ID (crypto.randomUUID or fallback).

    causationId?: string

    ID of the command that caused this one (set manually via payload.__causationId).

    correlationId?: string

    Correlation ID for tracing a chain of commands (propagates from parent).

    idempotencyKey?: string

    Idempotency key stamped by the idempotent plugin. Transports (e.g. the HTTP bridge) forward it as an Idempotency-Key header so the backend can reject duplicate writes. Not set by default — only when idempotent runs.

    origin?: "user" | "remote" | "sync" | "replay" | "agent" | string & {}

    Where the command originated. undefined (the default) means local user code called dispatch directly. The core never sets this field — dispatchers that proxy external traffic (bridges, sync layers, replay tooling, agent endpoints) stamp it post-hoc via plugins so downstream plugins, hooks, and listeners can distinguish local intent from mirrored or machine-driven commands (e.g. skip re-broadcasting a 'sync' command, or audit-log everything marked 'agent').

    Well-known values: 'user', 'remote', 'sync', 'replay', 'agent' — but any string is accepted for custom origins.

    bus.use((cmd, next) => {
      if (cmd.meta?.origin === 'agent') console.info('LLM-driven:', cmd.action);
      return next();
    });

    Settings
    Member Visibility

    On This Page
    Properties