@mindot/will 0.1.0

package/src/stem/tracts/transport/stream.transport.ts

@@ -0,0 +1,152 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/transport/stream.ts
+// ─────────────────────────────────────────────────────────────
+//
+// StreamTransport — an in-process ExternalTransport.
+//
+// Selected the same way as LoopbackTransport / SocketIoTransport: pass an
+// instance as `config.transport`. Everything the Will emits — replies, chunks,
+// messages, and the observability channels (`session_log`, `token_report`) —
+// is delivered to the consumer's subscribed listeners instead of being written
+// to files or S3 inside the Will. The consumer owns persistence/forwarding
+// (Postgres, S3, Kafka, a billing meter, an SSE feed).
+//
+// `injectInbound()` lets the consumer drive inbound envelopes (messages,
+// percepts, acks) into the Will, mirroring LoopbackTransport.
+//
+// Files remain available in DEVELOPMENT only: the producers (SessionLogger,
+// TokenTracker) keep a local file mirror behind `fileLoggingEnabled()`.
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  ExternalTransport,
+  OutboundEnvelope,
+  InboundEnvelope,
+  AckResult,
+  TransportStatus,
+} from './types'
+
+/** Channels a consumer can filter on (any OutboundEnvelope channel, or '*'). */
+export type StreamChannel = OutboundEnvelope['channel'] | '*'
+export type OutboundListener = ( env: OutboundEnvelope ) => void
+
+export class StreamTransport implements ExternalTransport {
+  readonly willId: string
+
+  private _connected = true
+  private readonly _outbound       = new Set<OutboundListener>()
+  private readonly _outboundByCh   = new Map<string, Set<OutboundListener>>()
+  private readonly _inboundHandlers = new Set<( env: InboundEnvelope ) => void>()
+  private readonly _statusHandlers  = new Set<( s: TransportStatus ) => void>()
+
+  constructor( willId: string = 'stream' ){
+    this.willId = willId
+  }
+
+  get connected(): boolean { return this._connected }
+
+  // ── ExternalTransport: Will → consumer ──────────────────────
+
+  /**
+   * Deliver an outbound envelope to subscribers. In-process and synchronous, so
+   * it resolves immediately (`via: 'event'`) — there is no remote peer to ack.
+   * A listener that throws is isolated; it can never break the tick loop.
+   */
+  async emit( env: OutboundEnvelope ): Promise<AckResult> {
+    this._dispatch( this._outbound, env )
+    this._dispatch( this._outboundByCh.get( env.channel ), env )
+    return { acked: true, via: 'event' }
+  }
+
+  // ── Consumer subscription (Will → consumer) ─────────────────
+
+  /** Subscribe to every outbound envelope. Returns an unsubscribe function. */
+  subscribe( listener: OutboundListener ): () => void {
+    this._outbound.add( listener )
+    return () => { this._outbound.delete( listener ) }
+  }
+
+  /**
+   * Subscribe to a single channel (e.g. `'token_report'`, `'session_log'`,
+   * `'reply'`) or `'*'` for all. Returns an unsubscribe function.
+   */
+  on( channel: StreamChannel, listener: OutboundListener ): () => void {
+    if( channel === '*' ) return this.subscribe( listener )
+    let set = this._outboundByCh.get( channel )
+    if( !set ){ set = new Set(); this._outboundByCh.set( channel, set ) }
+    set.add( listener )
+    return () => { set!.delete( listener ) }
+  }
+
+  // ── Consumer → Will (inbound) ───────────────────────────────
+
+  /**
+   * Inject an inbound envelope (message, percept, ack) into the Will. The stem
+   * enqueues it onto the tick-stamped InboundQueue and applies it deterministically
+   * on tick — this method itself never touches simulation state.
+   */
+  injectInbound( env: InboundEnvelope ): void {
+    for( const fn of this._inboundHandlers ){
+      try { fn( env ) }
+      catch { /* handler fault isolated */ }
+    }
+  }
+
+  onInbound( handler: ( env: InboundEnvelope ) => void ): () => void {
+    this._inboundHandlers.add( handler )
+    return () => { this._inboundHandlers.delete( handler ) }
+  }
+
+  onStatus( handler: ( s: TransportStatus ) => void ): () => void {
+    this._statusHandlers.add( handler )
+    return () => { this._statusHandlers.delete( handler ) }
+  }
+
+  /** Notify status subscribers (e.g. flip to 'disconnected' in a test). */
+  setStatus( status: TransportStatus ): void {
+    this._connected = status === 'connected'
+    for( const fn of this._statusHandlers ){
+      try { fn( status ) }
+      catch { /* isolated */ }
+    }
+  }
+
+  close(): void {
+    this._connected = false
+    this._outbound.clear()
+    this._outboundByCh.clear()
+    this._inboundHandlers.clear()
+    this._statusHandlers.clear()
+  }
+
+  /** Total active outbound listeners (diagnostics/tests). */
+  get listenerCount(): number {
+    let n = this._outbound.size
+    for( const set of this._outboundByCh.values() ) n += set.size
+    return n
+  }
+
+  private _dispatch( set: Set<OutboundListener> | undefined, env: OutboundEnvelope ): void {
+    if( !set ) return
+    for( const fn of set ){
+      try { fn( env ) }
+      catch { /* consumer listener must never break the Will */ }
+    }
+  }
+}
+
+/**
+ * Whether producers should ALSO write their telemetry to local files.
+ *
+ * Files are a development convenience only. In production the stream/transport is
+ * the single source of truth and the consumer owns persistence.
+ *
+ * - `WILL_FILE_LOGS=true|1|false|0` — explicit override (wins).
+ * - otherwise: on when `NODE_ENV` is neither `production` nor `test`.
+ */
+export function fileLoggingEnabled(): boolean {
+  const override = process.env['WILL_FILE_LOGS']
+  if( override !== undefined ) return override === 'true' || override === '1'
+  const env = process.env['NODE_ENV']
+  return env !== 'production' && env !== 'test'
+}

package/src/stem/tracts/transport/types.ts

@@ -0,0 +1,193 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/transport/types.ts
+// ─────────────────────────────────────────────────────────────
+//
+// ExternalTransport — Will's unified bidirectional channel to its host peer
+// (in production, a socket.io server owned by the backend).
+//
+// Replaces the per-concern, tick-drained SSE delivery model with a single
+// envelope channel carrying every outbound concern (replies, chunks, outbox
+// messages, effector invocations, activity) and every inbound concern (messages,
+// percepts, acks).
+//
+// DETERMINISM CONTRACT (see EXTERNAL_TRANSPORT_TODO.md § guardrails):
+//   - This module and its implementations live ONLY under src/stem/tracts/.
+//     Nothing under src/cognition/ may import it.
+//   - Outbound emit() is a pure side effect — it never mutates simulation state.
+//   - Inbound is NOT applied here. The stem enqueues every InboundEnvelope onto
+//     the tick-stamped InboundQueue; the tick loop applies it deterministically.
+//   - wallTime is telemetry only (R2) — never feed it into replay-sensitive state.
+// ─────────────────────────────────────────────────────────────
+
+import type { effectorInvocation, OutboxMessage } from '#types'
+
+// ── Shared base ────────────────────────────────────────────────
+
+interface BaseEnvelope {
+  /** Will instance this envelope belongs to (routing key for the peer). */
+  willId:        string
+  /**
+   * Stable id used to match an outbound envelope to its ack(s).
+   * For messages this is the OutboxMessage id; for effector invocations the
+   * decisionRecordId; for replies/chunks a generated id.
+   */
+  correlationId: string
+  /** Monotonic per-Will sequence number — ordering + dedup at the peer. */
+  seq:           number
+  /** Wall-clock emit/arrival time. Telemetry only (R2) — never replay state. */
+  wallTime:      number
+}
+
+// ── Outbound (Will → peer) ─────────────────────────────────────
+
+/** Facet reply, assembled. Fast path — emitted the instant the facet decides. */
+export interface ReplyEnvelope extends BaseEnvelope {
+  channel:           'reply'
+  entityId:          string
+  threadId:          string
+  bubbles:           string[]
+  replyToMessageId?: string
+}
+
+/** One streamed LLM token for a live conversation. Fast path, best-effort. */
+export interface ChunkEnvelope extends BaseEnvelope {
+  channel:  'chunk'
+  entityId: string
+  threadId: string
+  content:  string
+}
+
+/** Generic outbox message (talk/text/gesture/broadcast). Bridged on tick drain. */
+export interface MessageEnvelope extends BaseEnvelope {
+  channel: 'message'
+  message: OutboxMessage
+}
+
+/** External effector call for the peer/host to execute. Result returns via ack. */
+export interface effectorInvocationEnvelope extends BaseEnvelope {
+  channel:    'effector_invocation'
+  invocation: effectorInvocation
+}
+
+/** Projection of a cognitive percept — observability only. */
+export interface PerceptEnvelope extends BaseEnvelope {
+  channel: 'percept'
+  domain:  string
+  payload: Record<string, unknown>
+}
+
+/** Plan/activity event for the peer's activity stream. */
+export interface ActivityEnvelope extends BaseEnvelope {
+  channel:   'activity'
+  entityId:  string
+  eventType: string
+  payload:   Record<string, unknown>
+}
+
+/**
+ * A SessionLogger NDJSON entry — observability. Emitted so the consumer owns log
+ * persistence (Postgres, S3, Kafka, …) instead of the Will writing files/S3.
+ */
+export interface SessionLogEnvelope extends BaseEnvelope {
+  channel: 'session_log'
+  entry:   Record<string, unknown>
+}
+
+/**
+ * One attributed token/cost ledger record — observability + billing. Carries the
+ * 5-axis attribution (category/attribute/function/scope/label) + tokens + costUsd
+ * so the consumer can meter and re-bill end-users straight off the stream.
+ */
+export interface TokenReportEnvelope extends BaseEnvelope {
+  channel: 'token_report'
+  report:  Record<string, unknown>
+}
+
+export type OutboundEnvelope =
+  | ReplyEnvelope
+  | ChunkEnvelope
+  | MessageEnvelope
+  | effectorInvocationEnvelope
+  | PerceptEnvelope
+  | ActivityEnvelope
+  | SessionLogEnvelope
+  | TokenReportEnvelope
+
+// ── Inbound (peer → Will) ──────────────────────────────────────
+
+/** Conversational text/voice from an external entity. */
+export interface InboundMessageEnvelope extends BaseEnvelope {
+  channel:    'inbound_message'
+  kind:       'text' | 'voice'
+  entityId:   string
+  threadId:   string
+  content:    string
+  speakerName?: string
+}
+
+/** A non-conversational external percept (webhook, system signal, etc.). */
+export interface InboundPerceptEnvelope extends BaseEnvelope {
+  channel: 'inbound_percept'
+  domain:  string
+  payload: Record<string, unknown>
+}
+
+/**
+ * Acknowledgement for a prior outbound envelope.
+ *   - 'delivery' → receipt confirmation (edge-level; updates outbox status)
+ *   - 'result'   → effector execution result (crosses determinism boundary →
+ *                  applied on tick via confirmExecution)
+ * `correlationId` points back to the acked outbound envelope.
+ */
+export interface AckEnvelope extends BaseEnvelope {
+  channel:  'ack'
+  ackKind:  'delivery' | 'result'
+  delivered?: boolean
+  result?: {
+    success:     boolean
+    description: string
+    metrics?:    Record<string, number>
+  }
+}
+
+export type InboundEnvelope =
+  | InboundMessageEnvelope
+  | InboundPerceptEnvelope
+  | AckEnvelope
+
+export type Envelope = OutboundEnvelope | InboundEnvelope
+
+// ── Transport interface ────────────────────────────────────────
+
+export type TransportStatus = 'connected' | 'disconnected' | 'reconnecting'
+
+export interface AckResult {
+  acked:    boolean
+  via:      'callback' | 'event' | 'timeout'
+  payload?: unknown
+}
+
+export interface ExternalTransport {
+  /** True when a live connection to the peer exists. */
+  readonly connected: boolean
+
+  /**
+   * Emit an outbound envelope. Resolves when the peer acks (via socket.io ack
+   * callback) or the ack times out. Resolution NEVER mutates simulation state —
+   * the caller decides what to do with the AckResult (e.g. requeue the outbox).
+   */
+  emit( env: OutboundEnvelope, opts?: { ackTimeoutMs?: number } ): Promise<AckResult>
+
+  /**
+   * Register a handler for inbound envelopes. The stem's handler MUST do nothing
+   * but enqueue onto the InboundQueue — application happens on tick.
+   * Returns an unsubscribe function.
+   */
+  onInbound( handler: ( env: InboundEnvelope ) => void ): () => void
+
+  /** Connection lifecycle notifications (for buffer flush on reconnect). */
+  onStatus( handler: ( status: TransportStatus ) => void ): () => void
+
+  /** Tear down the connection and all handlers. */
+  close(): void
+}