dsh-realtime 0.2.1 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Travis Driessen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/index.d.ts

@@ -9,10 +9,12 @@
  * @module dsh-realtime
  */
 import { Service, type Context } from '@deepseek-ai/cordis';
+import { Journal } from './journal.ts';
 import type { RealtimeDelegation, RealtimeModelInfo, RealtimeProviderInfo, RealtimeSession, RealtimeSessionHandlers, RealtimeSessionOptions } from './types.ts';
 export * from './types.ts';
 export * from './error.ts';
 export * from './redact.ts';
+export * from './journal.ts';
 export { RealtimeError, REALTIME_ERROR_CODES } from './error.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -82,6 +84,14 @@ export declare abstract class RealtimeAdapter {
  */
 export declare class RealtimeRuntime extends Service {
     private readonly adapters;
+    /**
+     * The journal every plugin in this bundle writes to, and the diagnostics route serves.
+     *
+     * Owned here because this is the only object all of them already hold: the responder knows the
+     * delegation, the audio route knows the socket, and the seam is where those two meet. One journal
+     * per process — a reader should not be left correlating three partial ones.
+     */
+    readonly journal: Journal;
     /**
      * @param ctx - the Cordis context this service is mounted on.
      */

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,QAAQ,EAAE,eAAe,CAAA;KAC1B;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,IAAI,CAAA;IACR;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,8BAAsB,eAAe;IACnC;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEnE;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5E;AAQD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;OAEG;IACH,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,yBAAyB,CAiCxF;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgCf;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IASd;;;OAGG;IACH,aAAa,IAAI,oBAAoB,EAAE,CAEtC;IAED;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe/D;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBvE;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;CACF;AAED,qFAAqF;AACrF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAA;eAE5C,eAAe"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,YAAY,CAAA;AAEnB,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,QAAQ,EAAE,eAAe,CAAA;KAC1B;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,IAAI,CAAA;IACR;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,8BAAsB,eAAe;IACnC;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAEnE;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC5E;AAQD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAElE;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,UAAgB;IAEhC;;OAEG;IACH,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,yBAAyB,CAiCxF;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO;IAgCf;;;;;OAKG;IACH,OAAO,CAAC,MAAM;IASd;;;OAGG;IACH,aAAa,IAAI,oBAAoB,EAAE,CAEtC;IAED;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe/D;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBvE;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;CACF;AAED,qFAAqF;AACrF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAA;eAE5C,eAAe"}

package/lib/index.js

@@ -10,9 +10,11 @@
  */
 import { Service } from '@deepseek-ai/cordis';
 import { REALTIME_ERROR_CODES, RealtimeError } from './error.js';
+import { Journal } from './journal.js';
 export * from './types.js';
 export * from './error.js';
 export * from './redact.js';
+export * from './journal.js';
 export { RealtimeError, REALTIME_ERROR_CODES } from './error.js';
 /**
  * Provider-wire adapter for the realtime session vocabulary.
@@ -50,6 +52,14 @@ export class RealtimeAdapter {
  */
 export class RealtimeRuntime extends Service {
     adapters = new Map();
+    /**
+     * The journal every plugin in this bundle writes to, and the diagnostics route serves.
+     *
+     * Owned here because this is the only object all of them already hold: the responder knows the
+     * delegation, the audio route knows the socket, and the seam is where those two meet. One journal
+     * per process — a reader should not be left correlating three partial ones.
+     */
+    journal = new Journal();
     /**
      * @param ctx - the Cordis context this service is mounted on.
      */

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/journal.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The journal: a bounded, redaction-safe record of what the plugin did.
+ *
+ * S1 story 2, and the substrate for the rest of the sprint — the diagnostics route serves it, the
+ * spoken failures narrate from it, and the fault-injection matrix asserts against it. It exists
+ * because every failure this project has spent hours on was *unobservable* rather than wrong: the
+ * delegation that produced nothing, the append nobody heard, the socket the host refused. A journal
+ * turns each of those into a line.
+ *
+ * Three properties are load-bearing, and each is a test rather than a promise:
+ *
+ * - **Redaction happens on write, not on read.** A journal that stores the raw text and redacts when
+ *   serving it has already leaked: the secret is in memory, in a crash dump, and in whatever later
+ *   edit forgets the second step. Every string is passed through {@link redact} *before* it is
+ *   retained, so there is no unredacted copy to forget about. (That is design.md invariant 3 —
+ *   credentials proven safe by a test that fails on a planted string.)
+ * - **Bounded, with eviction visible.** The buffer keeps the last `capacity` entries. Every entry
+ *   carries a monotonic {@link JournalEntry.seq}, so a reader can tell that earlier entries were
+ *   dropped rather than never recorded — a ring buffer that silently truncates is how "the log is
+ *   empty" becomes indistinguishable from "nothing happened".
+ * - **Ack is not delivery.** Invariant 6: an acknowledgement proves injection, not that anyone heard
+ *   it. `append.acknowledged` and `speech.played` are separate kinds with separate entries, and
+ *   nothing here merges them into one "sent" line.
+ *
+ * @module dsh-realtime/journal
+ */
+/** Entries retained when a caller does not say otherwise. */
+export declare const DEFAULT_JOURNAL_CAPACITY = 200;
+/**
+ * What a journal entry can describe.
+ *
+ * The list is deliberately small and closed: an entry kind is a contract with whatever reads the
+ * journal later, so adding one is a considered act rather than a free-form log line.
+ */
+export type JournalKind = 
+/** A voice session opened, or was asked to and could not. */
+'session.opened' | 'session.closed' | 'session.failed'
+/**
+ * The audio route accepted a socket, refused one and said why, or watched one leave.
+ *
+ * A close is recorded rather than left to be inferred from the absence of later entries: a reader
+ * looking at a journal that simply stops cannot tell a client that hung up from a process that died,
+ * and that difference is the whole reason anybody opens the journal.
+ */
+ | 'socket.accepted' | 'socket.rejected' | 'socket.closed'
+/** The model raised a delegation, and the id it will be correlated by. */
+ | 'delegation.seen'
+/** A delegated turn was admitted to the session, refused, declined, or ran out of window. */
+ | 'prompt.admitted' | 'prompt.refused' | 'prompt.declined' | 'window.elapsed'
+/** A turn produced an answer. */
+ | 'answer.received'
+/** A context append was acknowledged on the wire. Not delivery — see invariant 6. */
+ | 'append.acknowledged'
+/** Audio was handed to the transport. **Not** a claim that anyone heard it. */
+ | 'speech.sent'
+/** The configuration as resolved, so a journal can be read without the profile beside it. */
+ | 'config.resolved';
+/** One retained entry. */
+export interface JournalEntry {
+    /**
+     * Monotonic sequence number, never reused and never reset within one journal instance.
+     *
+     * A gap between the oldest retained `seq` and the newest means entries were evicted, which is the
+     * difference between "nothing happened" and "the buffer rolled over".
+     */
+    readonly seq: number;
+    /** Milliseconds since the epoch, as the injecting caller saw it. */
+    readonly at: number;
+    /** What happened. */
+    readonly kind: JournalKind;
+    /** Redacted detail fields; keys are the caller's, values are already safe to serve. */
+    readonly detail: Readonly<Record<string, string>>;
+}
+/** How a journal is constructed. */
+export interface JournalOptions {
+    /** Entries retained before the oldest is evicted. */
+    capacity?: number;
+    /**
+     * Values that must never appear in an entry, however they are spelled.
+     *
+     * The route's capability token is 32 random bytes of base64url: it has no prefix and no structure,
+     * so no pattern can catch it and only a caller holding it can name it. The provider key is
+     * normally caught by shape, but pass it here too — a seam that relies on shape alone fails the
+     * moment a vendor changes its prefix.
+     */
+    secrets?: readonly string[];
+}
+/**
+ * A bounded, redaction-safe journal of plugin activity.
+ *
+ * Not a service: it is a plain object so it can be constructed in a test, handed to a route, and
+ * read without a Cordis context. The seam owns one instance and lends it to the plugins that write
+ * to it.
+ */
+export declare class Journal {
+    private readonly capacity;
+    private readonly secrets;
+    private readonly entries;
+    private nextSeq;
+    /**
+     * @param options - capacity and the values that must never be retained.
+     * @throws RangeError when `capacity` is not a positive integer — a journal that retains nothing
+     *   is a failure that looks like silence, which is the defect this module exists to remove.
+     */
+    constructor(options?: JournalOptions);
+    /**
+     * Add values that must never be retained, from a plugin that has only just learned them.
+     *
+     * Additive rather than a constructor argument because secrets arrive with the plugins that hold
+     * them, and plugins load in no guaranteed order: the route's capability token does not exist until
+     * the plugin that mints it applies, and a provider key arrives with whichever plugin reads the
+     * environment. A journal that could only be seeded at construction would have to be replaced to
+     * learn either — which is how a sink ends up with two instances and a reader with half a story.
+     * @param values - secrets to add; empty and duplicate values are ignored.
+     */
+    addSecrets(values: readonly string[]): void;
+    /**
+     * Redact and retain one entry, evicting the oldest when the buffer is full.
+     * @param kind - what happened.
+     * @param detail - string fields to retain; every value is redacted before it is stored.
+     * @param at - epoch milliseconds; defaults to now, and is injectable so a test can pin a time.
+     * @returns the entry exactly as it was retained, so a caller can correlate on `seq`.
+     */
+    record(kind: JournalKind, detail?: Readonly<Record<string, string>>, at?: number): JournalEntry;
+    /**
+     * Every retained entry, oldest first.
+     *
+     * Detached: mutating the result cannot reach the journal, so a route serving this cannot be used
+     * to tamper with the record it is reporting.
+     * @returns a detached, chronologically ordered copy.
+     */
+    snapshot(): JournalEntry[];
+    /** Entries currently retained. */
+    get size(): number;
+    /** Sequence number of the oldest retained entry, or `undefined` when empty. */
+    get oldestSeq(): number | undefined;
+}
+//# sourceMappingURL=journal.d.ts.map

package/lib/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,WAAW;AACrB,6DAA6D;AAC3D,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB;AACxD;;;;;;GAMG;GACD,iBAAiB,GAAG,iBAAiB,GAAG,eAAe;AACzD,0EAA0E;GACxE,iBAAiB;AACnB,6FAA6F;GAC3F,iBAAiB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB;AAC7E,iCAAiC;GAC/B,iBAAiB;AACnB,qFAAqF;GACnF,qBAAqB;AACvB,+EAA+E;GAC7E,aAAa;AACf,6FAA6F;GAC3F,iBAAiB,CAAA;AAErB,0BAA0B;AAC1B,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,qBAAqB;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD;AAED,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,OAAO,CAAI;IAEnB;;;;OAIG;IACH,YAAY,OAAO,GAAE,cAAmB,EAOvC;IAED;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAK1C;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EAAE,EAAE,GAAE,MAAmB,GAAG,YAAY,CAgB9G;IAED;;;;;;OAMG;IACH,QAAQ,IAAI,YAAY,EAAE,CAEzB;IAED,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,+EAA+E;IAC/E,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;CACF"}

package/lib/journal.js

@@ -0,0 +1,117 @@
+/**
+ * The journal: a bounded, redaction-safe record of what the plugin did.
+ *
+ * S1 story 2, and the substrate for the rest of the sprint — the diagnostics route serves it, the
+ * spoken failures narrate from it, and the fault-injection matrix asserts against it. It exists
+ * because every failure this project has spent hours on was *unobservable* rather than wrong: the
+ * delegation that produced nothing, the append nobody heard, the socket the host refused. A journal
+ * turns each of those into a line.
+ *
+ * Three properties are load-bearing, and each is a test rather than a promise:
+ *
+ * - **Redaction happens on write, not on read.** A journal that stores the raw text and redacts when
+ *   serving it has already leaked: the secret is in memory, in a crash dump, and in whatever later
+ *   edit forgets the second step. Every string is passed through {@link redact} *before* it is
+ *   retained, so there is no unredacted copy to forget about. (That is design.md invariant 3 —
+ *   credentials proven safe by a test that fails on a planted string.)
+ * - **Bounded, with eviction visible.** The buffer keeps the last `capacity` entries. Every entry
+ *   carries a monotonic {@link JournalEntry.seq}, so a reader can tell that earlier entries were
+ *   dropped rather than never recorded — a ring buffer that silently truncates is how "the log is
+ *   empty" becomes indistinguishable from "nothing happened".
+ * - **Ack is not delivery.** Invariant 6: an acknowledgement proves injection, not that anyone heard
+ *   it. `append.acknowledged` and `speech.played` are separate kinds with separate entries, and
+ *   nothing here merges them into one "sent" line.
+ *
+ * @module dsh-realtime/journal
+ */
+import { redact } from './redact.js';
+/** Entries retained when a caller does not say otherwise. */
+export const DEFAULT_JOURNAL_CAPACITY = 200;
+/**
+ * A bounded, redaction-safe journal of plugin activity.
+ *
+ * Not a service: it is a plain object so it can be constructed in a test, handed to a route, and
+ * read without a Cordis context. The seam owns one instance and lends it to the plugins that write
+ * to it.
+ */
+export class Journal {
+    capacity;
+    secrets;
+    entries = [];
+    nextSeq = 1;
+    /**
+     * @param options - capacity and the values that must never be retained.
+     * @throws RangeError when `capacity` is not a positive integer — a journal that retains nothing
+     *   is a failure that looks like silence, which is the defect this module exists to remove.
+     */
+    constructor(options = {}) {
+        const capacity = options.capacity ?? DEFAULT_JOURNAL_CAPACITY;
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError(`journal capacity must be a positive integer, received ${String(capacity)}`);
+        }
+        this.capacity = capacity;
+        this.secrets = [...options.secrets ?? []];
+    }
+    /**
+     * Add values that must never be retained, from a plugin that has only just learned them.
+     *
+     * Additive rather than a constructor argument because secrets arrive with the plugins that hold
+     * them, and plugins load in no guaranteed order: the route's capability token does not exist until
+     * the plugin that mints it applies, and a provider key arrives with whichever plugin reads the
+     * environment. A journal that could only be seeded at construction would have to be replaced to
+     * learn either — which is how a sink ends up with two instances and a reader with half a story.
+     * @param values - secrets to add; empty and duplicate values are ignored.
+     */
+    addSecrets(values) {
+        for (const value of values) {
+            if (typeof value !== 'string' || value.length === 0)
+                continue;
+            if (!this.secrets.includes(value))
+                this.secrets.push(value);
+        }
+    }
+    /**
+     * Redact and retain one entry, evicting the oldest when the buffer is full.
+     * @param kind - what happened.
+     * @param detail - string fields to retain; every value is redacted before it is stored.
+     * @param at - epoch milliseconds; defaults to now, and is injectable so a test can pin a time.
+     * @returns the entry exactly as it was retained, so a caller can correlate on `seq`.
+     */
+    record(kind, detail = {}, at = Date.now()) {
+        const safe = {};
+        for (const [key, value] of Object.entries(detail)) {
+            safe[key] = redact(value, this.secrets);
+        }
+        const entry = Object.freeze({
+            seq: this.nextSeq++,
+            at,
+            kind,
+            detail: Object.freeze(safe),
+        });
+        this.entries.push(entry);
+        // `shift()` on a bounded array: the buffer is capped, so this stays O(capacity) at worst and
+        // the memory ceiling is a property of the type rather than of the caller's discipline.
+        while (this.entries.length > this.capacity)
+            this.entries.shift();
+        return entry;
+    }
+    /**
+     * Every retained entry, oldest first.
+     *
+     * Detached: mutating the result cannot reach the journal, so a route serving this cannot be used
+     * to tamper with the record it is reporting.
+     * @returns a detached, chronologically ordered copy.
+     */
+    snapshot() {
+        return this.entries.map(entry => ({ ...entry, detail: { ...entry.detail } }));
+    }
+    /** Entries currently retained. */
+    get size() {
+        return this.entries.length;
+    }
+    /** Sequence number of the oldest retained entry, or `undefined` when empty. */
+    get oldestSeq() {
+        return this.entries[0]?.seq;
+    }
+}
+//# sourceMappingURL=journal.js.map

package/lib/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAA;AAgE3C;;;;;;GAMG;AACH,MAAM,OAAO,OAAO;IACD,QAAQ,CAAQ;IAChB,OAAO,CAAU;IACjB,OAAO,GAAmB,EAAE,CAAA;IACrC,OAAO,GAAG,CAAC,CAAA;IAEnB;;;;OAIG;IACH,YAAY,OAAO,GAAmB,EAAE;QACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,wBAAwB,CAAA;QAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,UAAU,CAAC,yDAAyD,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;QACnG,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;IAC3C,CAAC;IAED;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAyB;QAClC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAQ;YAC7D,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC7D,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAiB,EAAE,MAAM,GAAqC,EAAE,EAAE,EAAE,GAAW,IAAI,CAAC,GAAG,EAAE;QAC9F,MAAM,IAAI,GAA2B,EAAE,CAAA;QACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QACzC,CAAC;QACD,MAAM,KAAK,GAAiB,MAAM,CAAC,MAAM,CAAC;YACxC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE;YACnB,EAAE;YACF,IAAI;YACJ,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;SAC5B,CAAC,CAAA;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,6FAA6F;QAC7F,uFAAuF;QACvF,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QAChE,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;;OAMG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAA;IAC/E,CAAC;IAED,kCAAkC;IAClC,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAA;IAC5B,CAAC;IAED,+EAA+E;IAC/E,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAA;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-realtime",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Realtime voice capability seam for DeepSeek Harness: a provider registry plus the session adapter base.",
   "type": "module",
   "main": "lib/index.js",
@@ -53,14 +53,14 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "scripts": {
-    "build": "tsc -b",
-    "typecheck": "tsc -b --dry"
-  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.4"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --dry"
   }
-}
+}

package/src/index.ts

@@ -11,6 +11,7 @@
 
 import { Service, type Context } from '@deepseek-ai/cordis'
 import { REALTIME_ERROR_CODES, RealtimeError } from './error.ts'
+import { Journal } from './journal.ts'
 import type {
   RealtimeDelegation,
   RealtimeModelInfo,
@@ -23,6 +24,7 @@ import type {
 export * from './types.ts'
 export * from './error.ts'
 export * from './redact.ts'
+export * from './journal.ts'
 export { RealtimeError, REALTIME_ERROR_CODES } from './error.ts'
 
 declare module '@deepseek-ai/cordis' {
@@ -109,6 +111,15 @@ interface AdapterRegistration {
 export class RealtimeRuntime extends Service {
   private readonly adapters = new Map<string, AdapterRegistration>()
 
+  /**
+   * The journal every plugin in this bundle writes to, and the diagnostics route serves.
+   *
+   * Owned here because this is the only object all of them already hold: the responder knows the
+   * delegation, the audio route knows the socket, and the seam is where those two meet. One journal
+   * per process — a reader should not be left correlating three partial ones.
+   */
+  readonly journal = new Journal()
+
   /**
    * @param ctx - the Cordis context this service is mounted on.
    */

package/src/journal.ts

@@ -0,0 +1,184 @@
+/**
+ * The journal: a bounded, redaction-safe record of what the plugin did.
+ *
+ * S1 story 2, and the substrate for the rest of the sprint — the diagnostics route serves it, the
+ * spoken failures narrate from it, and the fault-injection matrix asserts against it. It exists
+ * because every failure this project has spent hours on was *unobservable* rather than wrong: the
+ * delegation that produced nothing, the append nobody heard, the socket the host refused. A journal
+ * turns each of those into a line.
+ *
+ * Three properties are load-bearing, and each is a test rather than a promise:
+ *
+ * - **Redaction happens on write, not on read.** A journal that stores the raw text and redacts when
+ *   serving it has already leaked: the secret is in memory, in a crash dump, and in whatever later
+ *   edit forgets the second step. Every string is passed through {@link redact} *before* it is
+ *   retained, so there is no unredacted copy to forget about. (That is design.md invariant 3 —
+ *   credentials proven safe by a test that fails on a planted string.)
+ * - **Bounded, with eviction visible.** The buffer keeps the last `capacity` entries. Every entry
+ *   carries a monotonic {@link JournalEntry.seq}, so a reader can tell that earlier entries were
+ *   dropped rather than never recorded — a ring buffer that silently truncates is how "the log is
+ *   empty" becomes indistinguishable from "nothing happened".
+ * - **Ack is not delivery.** Invariant 6: an acknowledgement proves injection, not that anyone heard
+ *   it. `append.acknowledged` and `speech.played` are separate kinds with separate entries, and
+ *   nothing here merges them into one "sent" line.
+ *
+ * @module dsh-realtime/journal
+ */
+
+import { redact } from './redact.ts'
+
+/** Entries retained when a caller does not say otherwise. */
+export const DEFAULT_JOURNAL_CAPACITY = 200
+
+/**
+ * What a journal entry can describe.
+ *
+ * The list is deliberately small and closed: an entry kind is a contract with whatever reads the
+ * journal later, so adding one is a considered act rather than a free-form log line.
+ */
+export type JournalKind =
+  /** A voice session opened, or was asked to and could not. */
+  | 'session.opened' | 'session.closed' | 'session.failed'
+  /**
+   * The audio route accepted a socket, refused one and said why, or watched one leave.
+   *
+   * A close is recorded rather than left to be inferred from the absence of later entries: a reader
+   * looking at a journal that simply stops cannot tell a client that hung up from a process that died,
+   * and that difference is the whole reason anybody opens the journal.
+   */
+  | 'socket.accepted' | 'socket.rejected' | 'socket.closed'
+  /** The model raised a delegation, and the id it will be correlated by. */
+  | 'delegation.seen'
+  /** A delegated turn was admitted to the session, refused, declined, or ran out of window. */
+  | 'prompt.admitted' | 'prompt.refused' | 'prompt.declined' | 'window.elapsed'
+  /** A turn produced an answer. */
+  | 'answer.received'
+  /** A context append was acknowledged on the wire. Not delivery — see invariant 6. */
+  | 'append.acknowledged'
+  /** Audio was handed to the transport. **Not** a claim that anyone heard it. */
+  | 'speech.sent'
+  /** The configuration as resolved, so a journal can be read without the profile beside it. */
+  | 'config.resolved'
+
+/** One retained entry. */
+export interface JournalEntry {
+  /**
+   * Monotonic sequence number, never reused and never reset within one journal instance.
+   *
+   * A gap between the oldest retained `seq` and the newest means entries were evicted, which is the
+   * difference between "nothing happened" and "the buffer rolled over".
+   */
+  readonly seq: number
+  /** Milliseconds since the epoch, as the injecting caller saw it. */
+  readonly at: number
+  /** What happened. */
+  readonly kind: JournalKind
+  /** Redacted detail fields; keys are the caller's, values are already safe to serve. */
+  readonly detail: Readonly<Record<string, string>>
+}
+
+/** How a journal is constructed. */
+export interface JournalOptions {
+  /** Entries retained before the oldest is evicted. */
+  capacity?: number
+  /**
+   * Values that must never appear in an entry, however they are spelled.
+   *
+   * The route's capability token is 32 random bytes of base64url: it has no prefix and no structure,
+   * so no pattern can catch it and only a caller holding it can name it. The provider key is
+   * normally caught by shape, but pass it here too — a seam that relies on shape alone fails the
+   * moment a vendor changes its prefix.
+   */
+  secrets?: readonly string[]
+}
+
+/**
+ * A bounded, redaction-safe journal of plugin activity.
+ *
+ * Not a service: it is a plain object so it can be constructed in a test, handed to a route, and
+ * read without a Cordis context. The seam owns one instance and lends it to the plugins that write
+ * to it.
+ */
+export class Journal {
+  private readonly capacity: number
+  private readonly secrets: string[]
+  private readonly entries: JournalEntry[] = []
+  private nextSeq = 1
+
+  /**
+   * @param options - capacity and the values that must never be retained.
+   * @throws RangeError when `capacity` is not a positive integer — a journal that retains nothing
+   *   is a failure that looks like silence, which is the defect this module exists to remove.
+   */
+  constructor(options: JournalOptions = {}) {
+    const capacity = options.capacity ?? DEFAULT_JOURNAL_CAPACITY
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new RangeError(`journal capacity must be a positive integer, received ${String(capacity)}`)
+    }
+    this.capacity = capacity
+    this.secrets = [...options.secrets ?? []]
+  }
+
+  /**
+   * Add values that must never be retained, from a plugin that has only just learned them.
+   *
+   * Additive rather than a constructor argument because secrets arrive with the plugins that hold
+   * them, and plugins load in no guaranteed order: the route's capability token does not exist until
+   * the plugin that mints it applies, and a provider key arrives with whichever plugin reads the
+   * environment. A journal that could only be seeded at construction would have to be replaced to
+   * learn either — which is how a sink ends up with two instances and a reader with half a story.
+   * @param values - secrets to add; empty and duplicate values are ignored.
+   */
+  addSecrets(values: readonly string[]): void {
+    for (const value of values) {
+      if (typeof value !== 'string' || value.length === 0) continue
+      if (!this.secrets.includes(value)) this.secrets.push(value)
+    }
+  }
+
+  /**
+   * Redact and retain one entry, evicting the oldest when the buffer is full.
+   * @param kind - what happened.
+   * @param detail - string fields to retain; every value is redacted before it is stored.
+   * @param at - epoch milliseconds; defaults to now, and is injectable so a test can pin a time.
+   * @returns the entry exactly as it was retained, so a caller can correlate on `seq`.
+   */
+  record(kind: JournalKind, detail: Readonly<Record<string, string>> = {}, at: number = Date.now()): JournalEntry {
+    const safe: Record<string, string> = {}
+    for (const [key, value] of Object.entries(detail)) {
+      safe[key] = redact(value, this.secrets)
+    }
+    const entry: JournalEntry = Object.freeze({
+      seq: this.nextSeq++,
+      at,
+      kind,
+      detail: Object.freeze(safe),
+    })
+    this.entries.push(entry)
+    // `shift()` on a bounded array: the buffer is capped, so this stays O(capacity) at worst and
+    // the memory ceiling is a property of the type rather than of the caller's discipline.
+    while (this.entries.length > this.capacity) this.entries.shift()
+    return entry
+  }
+
+  /**
+   * Every retained entry, oldest first.
+   *
+   * Detached: mutating the result cannot reach the journal, so a route serving this cannot be used
+   * to tamper with the record it is reporting.
+   * @returns a detached, chronologically ordered copy.
+   */
+  snapshot(): JournalEntry[] {
+    return this.entries.map(entry => ({ ...entry, detail: { ...entry.detail } }))
+  }
+
+  /** Entries currently retained. */
+  get size(): number {
+    return this.entries.length
+  }
+
+  /** Sequence number of the oldest retained entry, or `undefined` when empty. */
+  get oldestSeq(): number | undefined {
+    return this.entries[0]?.seq
+  }
+}