jschoubben
debd703d4e
Task 3.7 of novox/hq ADR 0116, and the whole of the sdk's diff for the bus change. Three comments said AMQP where they meant 'message headers' and 'a broker client'; the code never spoke it, which is why no module is rebuilt for any of this (ADR 0039).
55 lines
2.6 KiB
TypeScript
55 lines
2.6 KiB
TypeScript
// 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 message 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;
|
|
}
|