/**
 * instrumentation.ts — stdout JSON event emitter for olam-cli.
 *
 * Phase 1b A3 of olam-host-suite-phase-1b-k3s-beta-flavour (plan
 * ~/.claude/plans/olam-host-suite-phase-1b-k3s-beta-flavour.md).
 *
 * Canonical event schema (Decision 21 — `olam.instr.v1`):
 *   {
 *     "schema": "olam.instr.v1",
 *     "event": "substrate.set" | "upgrade.complete",
 *     "install_id": "<uuid-v4-from-config>",
 *     "ts": "<ISO-8601-UTC>",
 *     <event-specific-fields>
 *   }
 *
 * Emission target: **stderr**, newline-delimited, each line prefixed with
 * `OLAM_INSTR ` so consumers can grep-distinguish from other stderr output.
 *
 * Why stderr (and not stdout)? olam-cli's existing stdout-JSON contracts
 * (e.g. `olam status --json`, `olam doctor --json`) reserve stdout for
 * command output that consumers parse positionally. Mixing instrumentation
 * into stdout breaks those contracts. stderr keeps the emitter
 * grep-distinguishable AND segregated from the data-plane output.
 *
 * Consumers: month-6 aggregator script (`scripts/aggregate-substrate-events.mjs`,
 * D20) groups events by `install_id` for Falsifiable signal thresholds 1+4.
 *
 * Defensive contract:
 *   - emit() MUST NOT throw if the config can't be read; falls back to a
 *     placeholder install_id ('unknown') + emits a one-line stderr WARN.
 *   - Schema is versioned (`olam.instr.v1`); v2 fields land additively.
 *     Consumers MUST tolerate unknown fields.
 */
export declare const INSTRUMENTATION_SCHEMA: "olam.instr.v1";
export declare const INSTRUMENTATION_PREFIX: "OLAM_INSTR ";
export type SubstrateSetEvent = {
    schema: typeof INSTRUMENTATION_SCHEMA;
    event: 'substrate.set';
    install_id: string;
    ts: string;
    substrate: 'compose' | 'kubernetes';
    flavor?: string;
};
export type UpgradeCompleteEvent = {
    schema: typeof INSTRUMENTATION_SCHEMA;
    event: 'upgrade.complete';
    install_id: string;
    ts: string;
    substrate: 'compose' | 'kubernetes';
    duration_ms: number;
    flavor?: string;
};
export type InstrumentationEvent = SubstrateSetEvent | UpgradeCompleteEvent;
export type EmitOpts = {
    /** Inject a stderr-like sink for tests; defaults to process.stderr. */
    stderr?: NodeJS.WritableStream;
    /** Inject a clock for tests; defaults to Date.now(). */
    now?: () => Date;
    /** Inject a config-reader for tests; defaults to readConfig(). */
    installIdProvider?: () => string;
};
/**
 * Emit a `substrate.set` event. Called by `olam substrate set` ONLY on success
 * (failure paths emit nothing — by design; thresholds count successful switches).
 *
 * @param payload — substrate + optional flavor
 * @param opts — test-only injection points (stderr / now / installIdProvider)
 */
export declare function emitSubstrateSet(payload: {
    substrate: 'compose' | 'kubernetes';
    flavor?: string;
}, opts?: EmitOpts): void;
/**
 * Emit an `upgrade.complete` event. Called by Phase C C2's substrate-aware
 * `olam upgrade` ONLY on success.
 *
 * @param payload — substrate + duration_ms (and optional flavor)
 * @param opts — test-only injection points
 */
export declare function emitUpgradeComplete(payload: {
    substrate: 'compose' | 'kubernetes';
    duration_ms: number;
    flavor?: string;
}, opts?: EmitOpts): void;
//# sourceMappingURL=instrumentation.d.ts.map