// The runtime shapes a module's own code touches — NOT the manifest schema, which the control
// plane owns and parses (in Go). What is here is what actually crosses the wire: the tool
// definition and the event envelope. They change rarely and deliberately (novox/hq ADR 0039).
//
// **The provisioning shapes are NOT here, and used to be — wrongly.** Grant, Credential and an
// Interface type lived here, exported and imported by nothing, and they described a grant with
// fields (`resource`, `consumer`) the live wire does not use: the wire is the contributions file,
// whose shape is in `provisioner/index.ts` and agrees with the Go side. Dead types that
// contradict the live wire are worse than none — they read as the contract and are not, which is
// exactly how ADR 0074 came to claim a drift that was not there. Removed.

/** A tool a module exposes through the mesh's command surface. */
export interface ToolDefinition {
  readonly name: string;
  readonly description: string;
  /** JSON-schema-shaped input contract; kept opaque here so tools own their own shapes. */
  readonly input: Readonly<Record<string, unknown>>;
  readonly run: (args: Readonly<Record<string, unknown>>) => Promise<unknown>;
}

/**
 * The metadata that rides an event as AMQP headers (novox/hq ADR 0042). An event's identity and
 * provenance live here, not in the body, so a consumer — or the broker, or an audit tool — reads
 * who/when/what without parsing the payload. An unknown `x-` header is ignored, not refused: an
 * event is observed by parties that need not all understand every header.
 */
export interface EventHeaders {
  /** A unique id — for dedup and audit (delivery is at-least-once). */
  readonly "x-event-id": string;
  /** The emitter: the module, context or node name. */
  readonly "x-source": string;
  /** The node it was emitted from. */
  readonly "x-node": string;
  /** Emit time, RFC-3339. */
  readonly "x-time": string;
  /** Always `application/json`. */
  readonly "content-type": string;
  /** The event or command that caused this one — tracing. */
  readonly "x-causation-id"?: string;
  /** A version of the body's shape, so a body evolves without silent misreads. */
  readonly "x-schema"?: string;
  readonly [header: string]: string | undefined;
}

/**
 * A message crossing the broker: a routing key and a JSON body, per-node addressed. For an event,
 * `headers` carries the ADR 0042 metadata; plain request/reply transport leaves it absent.
 */
export interface Envelope<T = unknown> {
  readonly key: string;
  readonly node: string;
  readonly body: T;
  readonly headers?: EventHeaders;
}