@equipe-tech/observability 0.2.1 → 0.3.5

package/dist/contract/ContractIndex.d.ts

@@ -0,0 +1,54 @@
+import type { AttributeClassification, TelemetryContract, TelemetryContractInput } from "./TelemetryContract.js";
+import type { EventKind } from "./TelemetryEvent.js";
+import type { MetricKind } from "./MetricDefinition.js";
+export type ContractIndexEventAttribute = {
+    readonly name: string;
+    readonly classification: AttributeClassification;
+};
+export type ContractIndexEvent = {
+    readonly name: string;
+    readonly kind: EventKind;
+    readonly attributes: ReadonlyArray<string>;
+    readonly attributeClassifications: ReadonlyArray<ContractIndexEventAttribute>;
+};
+export type ContractIndexMetric = {
+    readonly name: string;
+    readonly kind: MetricKind;
+    readonly unit: string;
+    readonly attributes: ReadonlyArray<string>;
+};
+export type ContractSignalReference = {
+    readonly kind: "event" | "metric";
+    readonly name: string;
+};
+export type ContractSignalAliasDefinition = {
+    readonly source: ContractSignalReference;
+    readonly target: ContractSignalReference;
+    readonly since: string;
+};
+export type ContractSignalAliasMetadata = {
+    readonly version: 1;
+    readonly aliases: ReadonlyArray<ContractSignalAliasDefinition>;
+};
+export type ContractSignalAlias = {
+    readonly kind: "event" | "metric";
+    readonly from: string;
+    readonly to: string;
+};
+export type ContractIndex = {
+    readonly index: 1;
+    readonly contractVersion: number;
+    readonly service: string;
+    readonly events: ReadonlyArray<ContractIndexEvent>;
+    readonly metrics: ReadonlyArray<ContractIndexMetric>;
+    readonly aliases: ReadonlyArray<ContractSignalAlias>;
+};
+export declare const maximumContractAliasCount = 4096;
+export declare const maximumContractAliasDepth = 128;
+export declare const maximumContractAliasTargets = 256;
+export declare class ContractIndexAliasError extends Error {
+    readonly code: "OBS_CONTRACT_ALIAS_COUNT_EXCEEDED" | "OBS_CONTRACT_ALIAS_DEPTH_EXCEEDED" | "OBS_CONTRACT_ALIAS_TARGETS_EXCEEDED" | "OBS_CONTRACT_ALIAS_CYCLE";
+    readonly name = "ContractIndexAliasError";
+    constructor(code: "OBS_CONTRACT_ALIAS_COUNT_EXCEEDED" | "OBS_CONTRACT_ALIAS_DEPTH_EXCEEDED" | "OBS_CONTRACT_ALIAS_TARGETS_EXCEEDED" | "OBS_CONTRACT_ALIAS_CYCLE", message: string);
+}
+export declare const contractIndex: <Definition extends TelemetryContractInput>(contract: TelemetryContract<Definition>, service: string, aliasMetadata?: ContractSignalAliasMetadata) => ContractIndex;

package/dist/contract/ContractIndex.js

@@ -0,0 +1,178 @@
+export const maximumContractAliasCount = 4_096;
+export const maximumContractAliasDepth = 128;
+export const maximumContractAliasTargets = 256;
+export class ContractIndexAliasError extends Error {
+    code;
+    name = "ContractIndexAliasError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const byName = (left, right) => left.name.localeCompare(right.name);
+const signalNamePattern = /^[a-z][a-z0-9_]*(?:[.][a-z][a-z0-9_]*)+$/;
+const isoDatePattern = /^\d{4}-\d{2}-\d{2}$/;
+const isIsoDate = (value) => {
+    if (!isoDatePattern.test(value))
+        return false;
+    const timestamp = Date.parse(`${value}T00:00:00.000Z`);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString().slice(0, 10) === value;
+};
+const aliasKey = (kind, name) => `${kind}\u0000${name}`;
+const buildAliasGraph = (aliases) => {
+    if (aliases.length > maximumContractAliasCount) {
+        throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_COUNT_EXCEEDED", `Contract aliases exceed the maximum count of ${maximumContractAliasCount}.`);
+    }
+    const adjacency = new Map();
+    for (const alias of aliases) {
+        const key = aliasKey(alias.kind, alias.from);
+        const targets = adjacency.get(key) ?? new Set();
+        targets.add(alias.to);
+        adjacency.set(key, targets);
+    }
+    const colors = new Map();
+    const depths = new Map();
+    const depth = (kind, source, traversed) => {
+        if (traversed > maximumContractAliasDepth) {
+            throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_DEPTH_EXCEEDED", `Contract alias depth exceeds the maximum of ${maximumContractAliasDepth}.`);
+        }
+        const key = aliasKey(kind, source);
+        const cached = depths.get(key);
+        if (cached !== undefined)
+            return cached;
+        if (colors.get(key) === "gray") {
+            throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_CYCLE", "Contract aliases contain a cycle.");
+        }
+        colors.set(key, "gray");
+        let value = 0;
+        for (const target of adjacency.get(key) ?? []) {
+            value = Math.max(value, 1 + depth(kind, target, traversed + 1));
+            if (value > maximumContractAliasDepth) {
+                throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_DEPTH_EXCEEDED", `Contract alias depth exceeds the maximum of ${maximumContractAliasDepth}.`);
+            }
+        }
+        colors.set(key, "black");
+        depths.set(key, value);
+        return value;
+    };
+    for (const alias of aliases)
+        depth(alias.kind, alias.from, 0);
+    const expansions = new Map();
+    const expand = (kind, source) => {
+        const key = aliasKey(kind, source);
+        const cached = expansions.get(key);
+        if (cached !== undefined)
+            return cached;
+        const targets = new Set([source]);
+        for (const target of adjacency.get(key) ?? []) {
+            for (const nestedTarget of expand(kind, target)) {
+                targets.add(nestedTarget);
+                if (targets.size > maximumContractAliasTargets) {
+                    throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_TARGETS_EXCEEDED", `Contract alias expansion exceeds the maximum of ${maximumContractAliasTargets} targets.`);
+                }
+            }
+        }
+        expansions.set(key, targets);
+        return targets;
+    };
+    return { expand };
+};
+const validatedAliases = (contract, metadata) => {
+    const eventEntries = [...contract.eventByName.values()];
+    const metricEntries = [...contract.metricByName.values()];
+    const events = new Map();
+    const metrics = new Map();
+    for (const event of eventEntries)
+        events.set(event.name, event);
+    for (const metric of metricEntries)
+        metrics.set(metric.name, metric);
+    if (metadata.aliases.length > maximumContractAliasCount) {
+        throw new ContractIndexAliasError("OBS_CONTRACT_ALIAS_COUNT_EXCEEDED", `Contract aliases exceed the maximum count of ${maximumContractAliasCount}.`);
+    }
+    const aliases = metadata.aliases.map((alias) => {
+        if (alias.source.kind !== alias.target.kind) {
+            throw new TypeError("Contract alias source and target kinds must match.");
+        }
+        if (!signalNamePattern.test(alias.source.name) || !signalNamePattern.test(alias.target.name)) {
+            throw new TypeError("Contract alias names must use the telemetry signal grammar.");
+        }
+        if (alias.source.name === alias.target.name) {
+            throw new TypeError("Contract alias source and target must differ.");
+        }
+        if (!isIsoDate(alias.since)) {
+            throw new TypeError("Contract alias since must be an ISO calendar date.");
+        }
+        return {
+            kind: alias.source.kind,
+            from: alias.source.name,
+            to: alias.target.name,
+        };
+    });
+    const aliasGraph = buildAliasGraph(aliases);
+    for (const alias of aliases)
+        aliasGraph.expand(alias.kind, alias.from);
+    for (const alias of aliases) {
+        const targetExists = alias.kind === "event" ? events.has(alias.to) : metrics.has(alias.to);
+        if (!targetExists) {
+            throw new TypeError(`Contract alias target ${alias.to} is not declared.`);
+        }
+    }
+    const metricSources = new Set(aliases.filter((alias) => alias.kind === "metric").map((alias) => alias.from));
+    for (const source of metricSources) {
+        const names = aliasGraph.expand("metric", source);
+        const targets = [...names].flatMap((name) => {
+            const metric = metrics.get(name);
+            return metric === undefined ? [] : [metric];
+        });
+        const first = targets[0];
+        if (first !== undefined &&
+            targets.some((target) => target.kind !== first.kind ||
+                target.unit !== first.unit ||
+                [...target.attributes.keys()].sort().join("\u0000") !==
+                    [...first.attributes.keys()].sort().join("\u0000"))) {
+            throw new TypeError(`Contract metric alias source ${source} targets incompatible kind, unit, or attributes.`);
+        }
+    }
+    const eventSources = new Set(aliases.filter((alias) => alias.kind === "event").map((alias) => alias.from));
+    for (const source of eventSources) {
+        const names = aliasGraph.expand("event", source);
+        const targets = [...names].flatMap((name) => {
+            const event = events.get(name);
+            return event === undefined ? [] : [event];
+        });
+        const first = targets[0];
+        const signature = (event) => [...event.attributes.entries()]
+            .map(([name, attribute]) => `${name}\u0000${attribute.classification}`)
+            .sort()
+            .join("\u0001");
+        if (first !== undefined &&
+            targets.some((target) => target.kind !== first.kind || signature(target) !== signature(first))) {
+            throw new TypeError(`Contract event alias source ${source} targets incompatible kind, attributes, or classifications.`);
+        }
+    }
+    return aliases.sort((left, right) => `${left.kind}\u0000${left.from}\u0000${left.to}`.localeCompare(`${right.kind}\u0000${right.from}\u0000${right.to}`));
+};
+export const contractIndex = (contract, service, aliasMetadata = { version: 1, aliases: [] }) => ({
+    index: 1,
+    contractVersion: contract.version,
+    service,
+    events: [...contract.eventByName.values()]
+        .map((event) => ({
+        name: event.name,
+        kind: event.kind,
+        attributes: [...event.attributes.keys()].sort(),
+        attributeClassifications: [...event.attributes.entries()]
+            .map(([name, attribute]) => ({ name, classification: attribute.classification }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    }))
+        .sort(byName),
+    metrics: [...contract.metricByName.values()]
+        .map((metric) => ({
+        name: metric.name,
+        kind: metric.kind,
+        unit: metric.unit,
+        attributes: [...metric.attributes.keys()].sort(),
+    }))
+        .sort(byName),
+    aliases: validatedAliases(contract, aliasMetadata),
+});

package/dist/contract/ContractSurface.d.ts

@@ -0,0 +1,111 @@
+import { Schema } from "effect";
+import type { AuditOutcome } from "../audit/AuditRecord.js";
+import type { AttributeClassification, TelemetryContract, TelemetryContractInput } from "./TelemetryContract.js";
+import type { EventKind } from "./TelemetryEvent.js";
+import type { MetricKind, MetricAttributeScalar } from "./MetricDefinition.js";
+import type { ContractSignalAliasMetadata } from "./ContractIndex.js";
+export type ContractSurfaceEventAttribute = {
+    readonly name: string;
+    readonly required: boolean;
+    readonly classification: AttributeClassification;
+    readonly metricLabel: boolean;
+};
+export type ContractSurfaceEvent = {
+    readonly name: string;
+    readonly kind: EventKind;
+    readonly outcomeMeaning: ReadonlyArray<string>;
+    readonly attributes: ReadonlyArray<ContractSurfaceEventAttribute>;
+};
+export type ContractSurfaceMetricAttribute = {
+    readonly name: string;
+    readonly classification: "public" | "internal";
+    readonly maximumCardinality: number;
+    readonly allowedValues: ReadonlyArray<MetricAttributeScalar>;
+};
+export type ContractSurfaceMetric = {
+    readonly name: string;
+    readonly kind: MetricKind;
+    readonly unit: string;
+    readonly boundaries: ReadonlyArray<number>;
+    readonly attributes: ReadonlyArray<ContractSurfaceMetricAttribute>;
+};
+export type ContractSurfaceAuditAction = {
+    readonly action: string;
+    readonly resourceType: string;
+    readonly allowedOutcomes: ReadonlyArray<AuditOutcome>;
+    readonly reasonCodes: ReadonlyArray<string>;
+};
+export type ContractSurfaceAlias = {
+    readonly kind: "event" | "metric";
+    readonly from: string;
+    readonly to: string;
+    readonly since: string;
+};
+export type ContractSurface = {
+    readonly surface: 1;
+    readonly service: string;
+    readonly contractVersion: number;
+    readonly events: ReadonlyArray<ContractSurfaceEvent>;
+    readonly metrics: ReadonlyArray<ContractSurfaceMetric>;
+    readonly auditActions: ReadonlyArray<ContractSurfaceAuditAction>;
+    readonly aliases: ReadonlyArray<ContractSurfaceAlias>;
+    readonly browserEnvelope: {
+        readonly version: number;
+        readonly batchFields: ReadonlyArray<string>;
+        readonly eventFields: ReadonlyArray<string>;
+    };
+    readonly retentionWindowDays: number;
+};
+export type ContractSurfaceInput<Definition extends TelemetryContractInput> = {
+    readonly contract: TelemetryContract<Definition>;
+    readonly service: string;
+    readonly aliases?: ContractSignalAliasMetadata;
+    readonly retentionWindowDays: number;
+};
+export declare const contractSurface: <Definition extends TelemetryContractInput>(input: ContractSurfaceInput<Definition>) => ContractSurface;
+export declare const ContractSurfaceSchema: Schema.Struct<{
+    readonly surface: Schema.Literal<1>;
+    readonly service: Schema.String;
+    readonly contractVersion: Schema.Int;
+    readonly events: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["request", "operation", "domain", "defect", "audit"]>;
+        readonly outcomeMeaning: Schema.$Array<Schema.String>;
+        readonly attributes: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly required: Schema.Boolean;
+            readonly classification: Schema.Literals<readonly ["public", "internal", "sensitive", "forbidden"]>;
+            readonly metricLabel: Schema.Boolean;
+        }>>;
+    }>>;
+    readonly metrics: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly kind: Schema.Literals<readonly ["counter", "histogram", "observable_gauge"]>;
+        readonly unit: Schema.String;
+        readonly boundaries: Schema.$Array<Schema.Number>;
+        readonly attributes: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly classification: Schema.Literals<readonly ["public", "internal"]>;
+            readonly maximumCardinality: Schema.Int;
+            readonly allowedValues: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean]>>;
+        }>>;
+    }>>;
+    readonly auditActions: Schema.$Array<Schema.Struct<{
+        readonly action: Schema.String;
+        readonly resourceType: Schema.String;
+        readonly allowedOutcomes: Schema.$Array<Schema.Literals<readonly ["success", "failure", "cancelled", "denied"]>>;
+        readonly reasonCodes: Schema.$Array<Schema.String>;
+    }>>;
+    readonly aliases: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["event", "metric"]>;
+        readonly from: Schema.String;
+        readonly to: Schema.String;
+        readonly since: Schema.String;
+    }>>;
+    readonly browserEnvelope: Schema.Struct<{
+        readonly version: Schema.Int;
+        readonly batchFields: Schema.$Array<Schema.String>;
+        readonly eventFields: Schema.$Array<Schema.String>;
+    }>;
+    readonly retentionWindowDays: Schema.Int;
+}>;

package/dist/contract/ContractSurface.js

@@ -0,0 +1,116 @@
+import { Schema } from "effect";
+import { browserEnvelopeMetadata } from "../BrowserEvents.js";
+const outcomeMeaning = (kind) => kind === "defect"
+    ? ["failure"]
+    : kind === "audit"
+        ? ["cancelled", "denied", "failure", "success"]
+        : ["cancelled", "failure", "success"];
+const byName = (left, right) => left.name.localeCompare(right.name);
+export const contractSurface = (input) => ({
+    surface: 1,
+    service: input.service,
+    contractVersion: input.contract.version,
+    events: [...input.contract.eventByName.values()]
+        .map((event) => ({
+        name: event.name,
+        kind: event.kind,
+        outcomeMeaning: outcomeMeaning(event.kind),
+        attributes: [...event.attributes.entries()]
+            .map(([name, attribute]) => ({
+            name,
+            required: attribute.required,
+            classification: attribute.classification,
+            metricLabel: attribute.metricLabel,
+        }))
+            .sort(byName),
+    }))
+        .sort(byName),
+    metrics: [...input.contract.metricByName.values()]
+        .map((metric) => ({
+        name: metric.name,
+        kind: metric.kind,
+        unit: metric.unit,
+        boundaries: metric.kind === "histogram" ? [...metric.boundaries] : [],
+        attributes: [...metric.attributes.entries()]
+            .map(([name, attribute]) => ({
+            name,
+            classification: attribute.classification,
+            maximumCardinality: attribute.maximumCardinality,
+            allowedValues: [...(attribute.allowedValues ?? [])],
+        }))
+            .sort(byName),
+    }))
+        .sort(byName),
+    auditActions: [...input.contract.auditActionByName.values()]
+        .map((action) => ({
+        action: action.action,
+        resourceType: action.resourceType,
+        allowedOutcomes: [...action.allowedOutcomes].sort(),
+        reasonCodes: [...action.reasonCodes].sort(),
+    }))
+        .sort((left, right) => left.action.localeCompare(right.action)),
+    aliases: [...(input.aliases?.aliases ?? [])]
+        .map((alias) => ({
+        kind: alias.source.kind,
+        from: alias.source.name,
+        to: alias.target.name,
+        since: alias.since,
+    }))
+        .sort((left, right) => `${left.kind}\u0000${left.from}\u0000${left.to}`.localeCompare(`${right.kind}\u0000${right.from}\u0000${right.to}`)),
+    browserEnvelope: browserEnvelopeMetadata,
+    retentionWindowDays: input.retentionWindowDays,
+});
+const PositiveSafeInteger = Schema.Int.check(Schema.isGreaterThan(0), Schema.makeFilter(Number.isSafeInteger, { expected: "a positive safe integer" }));
+const Scalar = Schema.Union([Schema.String, Schema.Number, Schema.Boolean]);
+const EventAttributeDocument = Schema.Struct({
+    name: Schema.String,
+    required: Schema.Boolean,
+    classification: Schema.Literals(["public", "internal", "sensitive", "forbidden"]),
+    metricLabel: Schema.Boolean,
+});
+const EventDocument = Schema.Struct({
+    name: Schema.String,
+    kind: Schema.Literals(["request", "operation", "domain", "defect", "audit"]),
+    outcomeMeaning: Schema.Array(Schema.String),
+    attributes: Schema.Array(EventAttributeDocument),
+});
+const MetricAttributeDocument = Schema.Struct({
+    name: Schema.String,
+    classification: Schema.Literals(["public", "internal"]),
+    maximumCardinality: Schema.Int,
+    allowedValues: Schema.Array(Scalar),
+});
+const MetricDocument = Schema.Struct({
+    name: Schema.String,
+    kind: Schema.Literals(["counter", "histogram", "observable_gauge"]),
+    unit: Schema.String,
+    boundaries: Schema.Array(Schema.Number),
+    attributes: Schema.Array(MetricAttributeDocument),
+});
+const AuditActionDocument = Schema.Struct({
+    action: Schema.String,
+    resourceType: Schema.String,
+    allowedOutcomes: Schema.Array(Schema.Literals(["success", "failure", "cancelled", "denied"])),
+    reasonCodes: Schema.Array(Schema.String),
+});
+const AliasDocument = Schema.Struct({
+    kind: Schema.Literals(["event", "metric"]),
+    from: Schema.String,
+    to: Schema.String,
+    since: Schema.String,
+});
+export const ContractSurfaceSchema = Schema.Struct({
+    surface: Schema.Literal(1),
+    service: Schema.String,
+    contractVersion: PositiveSafeInteger,
+    events: Schema.Array(EventDocument),
+    metrics: Schema.Array(MetricDocument),
+    auditActions: Schema.Array(AuditActionDocument),
+    aliases: Schema.Array(AliasDocument),
+    browserEnvelope: Schema.Struct({
+        version: PositiveSafeInteger,
+        batchFields: Schema.Array(Schema.String),
+        eventFields: Schema.Array(Schema.String),
+    }),
+    retentionWindowDays: Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(3_650)),
+});

package/dist/contract/EventName.d.ts

@@ -0,0 +1,6 @@
+import { Schema } from "effect";
+export declare const isReservedEventNamePart: (part: string) => boolean;
+export declare const EventName: Schema.brand<Schema.String, "EventName">;
+export type EventName = typeof EventName.Type;
+export declare const isValidEventName: (name: string) => boolean;
+export declare const isValidAttributeName: (name: string) => boolean;

package/dist/contract/EventName.js

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+const eventNamePattern = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*){1,3}$/;
+const attributeNamePattern = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
+const numericIdentifierPattern = /^\d+$/;
+const uuidIdentifierPattern = /^[0-9a-f]{8}(?:_[0-9a-f]{4}){3}_[0-9a-f]{12}$/;
+const longIdentifierPattern = /^(?=[a-z0-9_]{12,}$)(?=.*[a-z])(?=.*\d)[a-z0-9_]+$/;
+const reservedEventParts = new Set([
+    "production",
+    "prod",
+    "staging",
+    "stage",
+    "development",
+    "dev",
+    "test",
+    "local",
+    "sandbox",
+    "qa",
+    "preview",
+    "debug",
+    "info",
+    "warn",
+    "warning",
+    "fatal",
+    "critical",
+    "trace",
+    "verbose",
+    "severity",
+    "success",
+    "succeeded",
+    "failure",
+    "failed",
+    "cancelled",
+    "canceled",
+    "ok",
+    "outcome",
+    "errored",
+    "error",
+]);
+export const isReservedEventNamePart = (part) => reservedEventParts.has(part);
+export const EventName = Schema.String.check(Schema.makeFilter((name) => isValidEventName(name), { expected: "a valid telemetry event name" })).pipe(Schema.brand("EventName"));
+export const isValidEventName = (name) => {
+    if (name.length > 128 || !eventNamePattern.test(name)) {
+        return false;
+    }
+    if (name === "browser.error") {
+        return true;
+    }
+    return name
+        .split(".")
+        .every((part) => !isReservedEventNamePart(part) &&
+        !numericIdentifierPattern.test(part) &&
+        !uuidIdentifierPattern.test(part) &&
+        !longIdentifierPattern.test(part));
+};
+export const isValidAttributeName = (name) => name.length <= 128 && attributeNamePattern.test(name);

package/dist/contract/EventProducer.d.ts

@@ -0,0 +1,123 @@
+import { Context, Effect } from "effect";
+import { AuditOutcome, type AuditActorInput } from "../audit/AuditRecord.js";
+import { CorrelationContext } from "../Correlation.js";
+import { type AttributeDefinitionsInput, type AuditActionDefinitionInput, type CompiledEventDefinition, type EventContractRegistry, type CompiledAuditActionDefinition, type TelemetryContract, type TelemetryContractInput } from "./TelemetryContract.js";
+import type { BrowserEventError, BrowserTraceContext } from "../BrowserEvents.js";
+import { type AttributeValue, ErrorContext, type EventAttributes, EventOutcome, EventSeverity, HttpContext, type TelemetryEvent } from "./TelemetryEvent.js";
+import type { PolicyRedaction } from "../policy/PolicyTransform.js";
+import { InvalidTelemetryEvent } from "./TelemetryContractError.js";
+export type EventAdmissionMetadata = {
+    readonly policyDroppedAttributes: number;
+};
+export type BrowserTelemetryEvent = {
+    readonly id: string;
+    readonly name: string;
+    readonly occurredAt: number;
+    readonly attributes: EventAttributes;
+    readonly error?: BrowserEventError;
+    readonly trace?: BrowserTraceContext;
+    readonly admission: EventAdmissionMetadata;
+};
+export type BrowserEventBatchAdmission = {
+    readonly commit: Effect.Effect<void>;
+};
+declare const TelemetryEventSink_base: Context.ServiceClass<TelemetryEventSink, "@equipe-tech/observability/TelemetryEventSink", {
+    readonly record: (event: TelemetryEvent, admission: EventAdmissionMetadata) => Effect.Effect<void, InvalidTelemetryEvent>;
+    readonly admitBrowserBatch: (events: ReadonlyArray<BrowserTelemetryEvent>) => Effect.Effect<BrowserEventBatchAdmission, InvalidTelemetryEvent>;
+}>;
+export declare class TelemetryEventSink extends TelemetryEventSink_base {
+}
+type RequiredAttributeNames<Attributes extends AttributeDefinitionsInput> = {
+    readonly [Name in keyof Attributes]: Attributes[Name]["required"] extends true ? Name : never;
+}[keyof Attributes];
+type EventAttributesOf<Attributes extends AttributeDefinitionsInput> = {
+    readonly [Name in RequiredAttributeNames<Attributes>]: AttributeValue;
+} & {
+    readonly [Name in Exclude<keyof Attributes, RequiredAttributeNames<Attributes>>]?: AttributeValue;
+};
+type EventPayloadBase<Attributes extends AttributeDefinitionsInput> = {
+    readonly timestamp?: string;
+    readonly severity?: EventSeverity;
+    readonly correlation?: CorrelationContext;
+    readonly attributes: EventAttributesOf<Attributes>;
+};
+type AuditPayloadForAction<Action extends AuditActionDefinitionInput> = {
+    readonly outcome: Action["allowedOutcomes"][number];
+    readonly audit: {
+        readonly action: Action["action"];
+        readonly actor: AuditActorInput;
+        readonly resourceType: Action["resourceType"];
+        readonly resourceId: string;
+        readonly reasonCode?: string;
+    };
+};
+type AuditPayload<Definition extends TelemetryContractInput> = {
+    readonly [Alias in keyof Definition["auditActions"]]: AuditPayloadForAction<Definition["auditActions"][Alias]>;
+}[keyof Definition["auditActions"]];
+type EventPayloadForKind<Kind, Attributes extends AttributeDefinitionsInput, Definition extends TelemetryContractInput> = Kind extends "request" ? EventPayloadBase<Attributes> & {
+    readonly outcome: EventOutcome;
+    readonly durationMs: number;
+    readonly http: HttpContext;
+} : Kind extends "operation" ? EventPayloadBase<Attributes> & {
+    readonly outcome: EventOutcome;
+    readonly durationMs: number;
+} : Kind extends "domain" ? EventPayloadBase<Attributes> & {
+    readonly outcome: EventOutcome;
+} : Kind extends "defect" ? EventPayloadBase<Attributes> & {
+    readonly outcome?: never;
+    readonly error: ErrorContext;
+} : Kind extends "audit" ? EventPayloadBase<Attributes> & AuditPayload<Definition> : never;
+export type EventPayloadOf<Definition extends TelemetryContractInput, Alias extends keyof Definition["events"] & string> = EventPayloadForKind<Definition["events"][Alias]["kind"], Definition["events"][Alias]["attributes"], Definition>;
+export type EmitReceipt = {
+    readonly decision: "recorded";
+    readonly event: TelemetryEvent;
+    readonly redactions: ReadonlyArray<PolicyRedaction>;
+    readonly admission: EventAdmissionMetadata;
+    readonly contractProvenance: string;
+} | {
+    readonly decision: "sampled_out";
+    readonly name: string;
+    readonly contractProvenance: string;
+};
+export type EventProducer<Definition extends TelemetryContractInput> = {
+    readonly emit: <Alias extends keyof Definition["events"] & string>(alias: Alias, payload: EventPayloadOf<Definition, Alias>) => Effect.Effect<EmitReceipt, InvalidTelemetryEvent, TelemetryEventSink>;
+};
+type EmittedAttributes = {
+    readonly [attributeName: string]: AttributeValue | undefined;
+};
+type AuditContextInput = {
+    readonly action: string;
+    readonly actor: AuditActorInput;
+    readonly resourceType: string;
+    readonly resourceId: string;
+    readonly reasonCode?: string;
+};
+type AdmissionContract = EventContractRegistry & {
+    readonly auditActionByName: ReadonlyMap<string, CompiledAuditActionDefinition>;
+};
+export type CanonicalEventPayload = {
+    readonly timestamp?: string;
+    readonly severity?: EventSeverity;
+    readonly correlation?: CorrelationContext;
+    readonly attributes: EmittedAttributes;
+    readonly outcome?: AuditOutcome;
+    readonly durationMs?: number;
+    readonly http?: HttpContext;
+    readonly error?: ErrorContext;
+    readonly audit?: AuditContextInput;
+};
+export declare const admitEvent: (contract: AdmissionContract, definition: CompiledEventDefinition, payload: CanonicalEventPayload) => Effect.Effect<{
+    decision: "sampled_out";
+    name: string & import("effect/Brand").Brand<"EventName">;
+    event?: never;
+    redactions?: never;
+    admission?: never;
+} | {
+    name?: never;
+    decision: "recorded";
+    event: TelemetryEvent;
+    redactions: readonly PolicyRedaction[];
+    admission: EventAdmissionMetadata;
+}, InvalidTelemetryEvent, never>;
+export declare const makeEventProducer: <const Definition extends TelemetryContractInput>(contract: TelemetryContract<Definition>) => EventProducer<Definition>;
+export {};