/**
 * Canonical NATS message headers carrying protocol version + capabilities.
 *
 * MUST stay byte-identical with Go sesh `internal/subject/headers.go`.
 * Every outbound NATS message — request, reply, publish — should carry
 * `Sesh-Protocol-Version` and `Sesh-Capabilities`. `Sesh-Wire` is optional
 * and lets the shim dispatch between Synadia and A2A based on headers
 * rather than subject path.
 */

export const HEADER_PROTOCOL_VERSION = "Sesh-Protocol-Version";
export const HEADER_CAPABILITIES = "Sesh-Capabilities";
/** Optional. "synadia" | "a2a". When absent, the shim defaults to synadia. */
export const HEADER_WIRE = "Sesh-Wire";

export const CURRENT_PROTOCOL_VERSION = "0.4";
export const DEFAULT_CAPABILITIES = "messages,artifacts,cards";
export const WIRE_SYNADIA = "synadia";
export const WIRE_A2A = "a2a";

/**
 * Minimal structural type for a NATS headers map (matches `MsgHdrs` /
 * `MsgHdrsImpl` from `@nats-io/nats-core` without importing the type).
 */
export interface SeshHeaders {
  set(key: string, value: string): void;
}

/**
 * Stamp the canonical sesh headers (`Sesh-Protocol-Version`,
 * `Sesh-Capabilities`, and optionally `Sesh-Wire`) onto an existing
 * headers map. Mutates and returns the map for chaining.
 *
 * `wire` defaults to undefined (shim assumes Synadia). Pass `WIRE_A2A`
 * for outbound A2A traffic so the shim can dispatch correctly.
 */
export function stampSeshHeaders<H extends SeshHeaders>(
  headers: H,
  opts?: {
    capabilities?: string;
    wire?: string;
    protocolVersion?: string;
  },
): H {
  headers.set(HEADER_PROTOCOL_VERSION, opts?.protocolVersion ?? CURRENT_PROTOCOL_VERSION);
  headers.set(HEADER_CAPABILITIES, opts?.capabilities ?? DEFAULT_CAPABILITIES);
  if (opts?.wire !== undefined) headers.set(HEADER_WIRE, opts.wire);
  return headers;
}