@equipe-tech/observability 0.2.0 → 0.3.5

package/dist/contract/TelemetryContract.js

@@ -0,0 +1,451 @@
+import { Effect, Option, Schema } from "effect";
+import { AuditAction, AuditOutcome, AuditReasonCode, AuditResourceType, } from "../audit/AuditRecord.js";
+import { EventName, isValidAttributeName, isValidEventName } from "./EventName.js";
+import { EventKind, EventSeverity, } from "./TelemetryEvent.js";
+import { InvalidTelemetryContract, InvalidTelemetryEvent, } from "./TelemetryContractError.js";
+import { isValidHistogramBoundaries, isValidMetricAttributeCount, isValidMetricAttributeName, isValidMetricCardinality, isValidMetricDescription, isValidMetricName, isValidMetricUnit, validAllowedValues, } from "./MetricDefinition.js";
+export { isValidMetricName } from "./MetricDefinition.js";
+export const AttributeClassification = Schema.Literals([
+    "public",
+    "internal",
+    "sensitive",
+    "forbidden",
+]);
+export const defineEventDefinitions = (events) => events;
+export const telemetryContractDefinition = (definition) => definition;
+export const validateContractEvent = (contract, eventName, attributes) => {
+    const parsedEventName = EventName.makeOption(eventName);
+    const definition = Option.isSome(parsedEventName)
+        ? contract.eventByName.get(parsedEventName.value)
+        : undefined;
+    if (definition === undefined) {
+        return new InvalidTelemetryEvent({
+            code: "OBS_EVENT_UNKNOWN_NAME",
+            message: `Event "${eventName}" is not declared by the telemetry contract. Use a valid declared canonical event name.`,
+            eventName,
+        });
+    }
+    for (const required of definition.requiredAttributes) {
+        if (!Object.hasOwn(attributes, required)) {
+            return new InvalidTelemetryEvent({
+                code: "OBS_EVENT_MISSING_ATTRIBUTE",
+                message: `Event "${eventName}" is missing required attribute "${required}". Add the declared scalar attribute before emitting.`,
+                eventName,
+                attributeName: required,
+            });
+        }
+    }
+    for (const attributeName of Object.keys(attributes)) {
+        if (!definition.attributes.has(attributeName)) {
+            return new InvalidTelemetryEvent({
+                code: "OBS_EVENT_UNDECLARED_ATTRIBUTE",
+                message: `Event "${eventName}" does not declare attribute "${attributeName}". Add it to the contract or remove it from the event.`,
+                eventName,
+                attributeName,
+            });
+        }
+    }
+    return definition;
+};
+export const telemetryContractProvenance = (contract) => contract.provenance;
+const compareContractKeys = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const canonicalTelemetryContractProvenance = (definition) => JSON.stringify({
+    auditActions: Object.fromEntries(Object.entries(definition.auditActions)
+        .sort(([left], [right]) => compareContractKeys(left, right))
+        .map(([alias, action]) => [
+        alias,
+        {
+            action: action.action,
+            allowedOutcomes: action.allowedOutcomes,
+            reasonCodes: action.reasonCodes,
+            resourceType: action.resourceType,
+        },
+    ])),
+    events: Object.fromEntries(Object.entries(definition.events)
+        .sort(([left], [right]) => compareContractKeys(left, right))
+        .map(([alias, event]) => [
+        alias,
+        {
+            attributes: Object.fromEntries(Object.entries(event.attributes)
+                .sort(([left], [right]) => compareContractKeys(left, right))
+                .map(([name, attribute]) => [
+                name,
+                {
+                    classification: attribute.classification,
+                    metricLabel: attribute.metricLabel,
+                    required: attribute.required,
+                },
+            ])),
+            defaultSeverity: event.defaultSeverity,
+            kind: event.kind,
+            mandatory: event.mandatory,
+            name: event.name,
+            sampling: event.sampling.kind === "rate"
+                ? { kind: event.sampling.kind, rate: event.sampling.rate }
+                : { kind: event.sampling.kind },
+        },
+    ])),
+    metrics: Object.fromEntries(Object.entries(definition.metrics)
+        .sort(([left], [right]) => compareContractKeys(left, right))
+        .map(([alias, metric]) => [
+        alias,
+        {
+            attributes: Object.fromEntries(Object.entries(metric.attributes)
+                .sort(([left], [right]) => compareContractKeys(left, right))
+                .map(([name, attribute]) => [
+                name,
+                {
+                    allowedValues: attribute.allowedValues,
+                    classification: attribute.classification,
+                    maximumCardinality: attribute.maximumCardinality,
+                },
+            ])),
+            boundaries: metric.boundaries,
+            description: metric.description,
+            kind: metric.kind,
+            name: metric.name,
+            unit: metric.unit,
+        },
+    ])),
+    version: definition.version,
+});
+const immutableMap = (entries) => {
+    const values = new Map(entries);
+    let readonlyValues;
+    readonlyValues = Object.freeze({
+        get size() {
+            return values.size;
+        },
+        get: (key) => values.get(key),
+        has: (key) => values.has(key),
+        entries: () => values.entries(),
+        keys: () => values.keys(),
+        values: () => values.values(),
+        forEach(callback, thisArg) {
+            values.forEach((value, key) => callback.call(thisArg, value, key, readonlyValues));
+        },
+        [Symbol.iterator]: () => values[Symbol.iterator](),
+    });
+    return readonlyValues;
+};
+const freezeTelemetryContractDefinition = (definition) => {
+    for (const event of Object.values(definition.events)) {
+        Object.freeze(event.sampling);
+        Object.values(event.attributes).forEach(Object.freeze);
+        Object.freeze(event.attributes);
+        Object.freeze(event);
+    }
+    for (const metric of Object.values(definition.metrics)) {
+        if (metric.boundaries !== undefined)
+            Object.freeze(metric.boundaries);
+        for (const attribute of Object.values(metric.attributes)) {
+            if (attribute.allowedValues !== undefined)
+                Object.freeze(attribute.allowedValues);
+            Object.freeze(attribute);
+        }
+        Object.freeze(metric.attributes);
+        Object.freeze(metric);
+    }
+    for (const action of Object.values(definition.auditActions)) {
+        Object.freeze(action.allowedOutcomes);
+        if (action.reasonCodes !== undefined)
+            Object.freeze(action.reasonCodes);
+        Object.freeze(action);
+    }
+    Object.freeze(definition.events);
+    Object.freeze(definition.metrics);
+    Object.freeze(definition.auditActions);
+    return Object.freeze(definition);
+};
+const isAttributeClassification = Schema.is(AttributeClassification);
+const isEventKind = Schema.is(EventKind);
+const isEventSeverity = Schema.is(EventSeverity);
+const isAuditAction = Schema.is(AuditAction);
+const isAuditOutcome = Schema.is(AuditOutcome);
+const isAuditReasonCode = Schema.is(AuditReasonCode);
+const isAuditResourceType = Schema.is(AuditResourceType);
+const canonicalSinkFields = new Set([
+    "event.name",
+    "event.kind",
+    "event.type",
+    "event.severity",
+    "event.outcome",
+    "event.timestamp",
+    "event.duration_ms",
+    "event.source",
+    "event.policy_dropped_attributes",
+    "browser.event.id",
+    "browser.event.occurred_at",
+    "http.request.method",
+    "http.route",
+    "http.response.status_code",
+    "error.type",
+    "error.name",
+    "error.message",
+    "error.status",
+    "error.retryable",
+    "audit.action",
+    "audit.actor.kind",
+    "audit.actor.id",
+    "audit.resource.type",
+    "audit.resource.id",
+    "audit.outcome",
+    "audit.reason_code",
+    "audit.tenant.id",
+    "audit.record.id",
+    "audit.record.hash",
+    "audit.occurred_at",
+    "audit.schema_version",
+    "request.id",
+    "run.id",
+]);
+const AttributeDefinitionDocument = Schema.Struct({
+    classification: Schema.String,
+    required: Schema.Boolean,
+    metricLabel: Schema.Boolean,
+});
+const EventDefinitionDocument = Schema.Struct({
+    name: Schema.String,
+    kind: Schema.String,
+    defaultSeverity: Schema.String,
+    mandatory: Schema.Boolean,
+    sampling: Schema.Struct({
+        kind: Schema.String,
+        rate: Schema.Number.pipe(Schema.optionalKey),
+    }),
+    attributes: Schema.Record(Schema.String, AttributeDefinitionDocument),
+});
+const MetricAttributeDefinitionDocument = Schema.Struct({
+    classification: Schema.String,
+    maximumCardinality: Schema.Number,
+    allowedValues: Schema.Array(Schema.Union([Schema.String, Schema.Number, Schema.Boolean])).pipe(Schema.optionalKey),
+});
+const MetricDefinitionDocument = Schema.Struct({
+    name: Schema.String,
+    description: Schema.String,
+    unit: Schema.String,
+    kind: Schema.String,
+    boundaries: Schema.Array(Schema.Number).pipe(Schema.optionalKey),
+    attributes: Schema.Record(Schema.String, MetricAttributeDefinitionDocument),
+});
+const AuditActionDefinitionDocument = Schema.Struct({
+    action: Schema.String,
+    resourceType: Schema.String,
+    allowedOutcomes: Schema.Array(Schema.String),
+    reasonCodes: Schema.Array(Schema.String).pipe(Schema.optionalKey),
+});
+const TelemetryContractDocument = Schema.Struct({
+    version: Schema.Number,
+    events: Schema.Record(Schema.String, EventDefinitionDocument),
+    metrics: Schema.Record(Schema.String, MetricDefinitionDocument),
+    auditActions: Schema.Record(Schema.String, AuditActionDefinitionDocument),
+});
+const decodeTelemetryContractDocument = Schema.decodeUnknownEffect(TelemetryContractDocument);
+const issue = (code, message, context = {}) => ({ code, message, ...context });
+const collectIssues = (definition) => {
+    const issues = [];
+    const eventAliasesByName = new Map();
+    const auditActionAliasesByName = new Map();
+    const metricAliasesByName = new Map();
+    if (!Number.isSafeInteger(definition.version) || definition.version <= 0) {
+        issues.push(issue("OBS_CONTRACT_INVALID_VERSION", "Telemetry contract version is invalid. Use a positive safe integer."));
+    }
+    for (const [alias, event] of Object.entries(definition.events)) {
+        if (!isValidEventName(event.name)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_EVENT_NAME", `Event "${event.name}" is invalid. Use two to four lowercase dot-separated parts without environment, severity, outcome, or identifier segments.`, { eventAlias: alias, eventName: event.name }));
+        }
+        const existingAlias = eventAliasesByName.get(event.name);
+        if (existingAlias !== undefined) {
+            issues.push(issue("OBS_CONTRACT_DUPLICATE_EVENT_NAME", `Event "${event.name}" is declared by aliases "${existingAlias}" and "${alias}". Give each event one canonical name.`, { eventAlias: alias, eventName: event.name }));
+        }
+        else {
+            eventAliasesByName.set(event.name, alias);
+        }
+        if (!isEventKind(event.kind)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_EVENT_KIND", `Event "${event.name}" has an invalid kind. Use request, operation, domain, defect, or audit.`, { eventAlias: alias, eventName: event.name }));
+        }
+        if (!isEventSeverity(event.defaultSeverity)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_DEFAULT_SEVERITY", `Event "${event.name}" has an invalid default severity. Use debug, info, warn, error, or fatal.`, { eventAlias: alias, eventName: event.name }));
+        }
+        if (event.sampling.kind === "rate") {
+            if (!Number.isFinite(event.sampling.rate) ||
+                event.sampling.rate <= 0 ||
+                event.sampling.rate > 1) {
+                issues.push(issue("OBS_CONTRACT_INVALID_SAMPLING_RATE", `Event "${event.name}" has an invalid sampling rate. Use a finite rate greater than zero and at most one.`, { eventAlias: alias, eventName: event.name }));
+            }
+        }
+        else if (event.sampling.kind !== "always") {
+            issues.push(issue("OBS_CONTRACT_INVALID_SAMPLING_RATE", `Event "${event.name}" has an invalid sampling policy. Use always or rate.`, { eventAlias: alias, eventName: event.name }));
+        }
+        for (const [attributeName, attribute] of Object.entries(event.attributes)) {
+            if (!isValidAttributeName(attributeName)) {
+                issues.push(issue("OBS_CONTRACT_INVALID_ATTRIBUTE_NAME", `Attribute "${attributeName}" is invalid. Use a dotted lowercase name no longer than 128 characters.`, { eventAlias: alias, eventName: event.name, attributeName }));
+            }
+            if (canonicalSinkFields.has(attributeName)) {
+                issues.push(issue("OBS_CONTRACT_RESERVED_ATTRIBUTE_NAME", `Attribute "${attributeName}" is a canonical sink field. Rename the application attribute.`, { eventAlias: alias, eventName: event.name, attributeName }));
+            }
+            if (!isAttributeClassification(attribute.classification) ||
+                ((attribute.classification === "sensitive" || attribute.classification === "forbidden") &&
+                    (attribute.required || attribute.metricLabel))) {
+                issues.push(issue("OBS_CONTRACT_INVALID_ATTRIBUTE_DEFINITION", `Attribute "${attributeName}" has an invalid classification or incompatible flags. Use public, internal, sensitive, or forbidden, and set required and metricLabel to false for restricted attributes.`, { eventAlias: alias, eventName: event.name, attributeName }));
+            }
+        }
+    }
+    for (const [alias, metric] of Object.entries(definition.metrics)) {
+        const metricName = metric.name;
+        const context = { metricAlias: alias, metricName };
+        if (!isValidMetricName(metric.name)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_NAME", `Metric "${metric.name}" is invalid. Use exactly two lowercase dot-separated parts, no reserved dimensions, and at most 128 characters.`, context));
+        }
+        const existingMetricAlias = metricAliasesByName.get(metric.name);
+        if (existingMetricAlias !== undefined) {
+            issues.push(issue("OBS_CONTRACT_DUPLICATE_METRIC_NAME", `Metric "${metric.name}" is declared by aliases "${existingMetricAlias}" and "${alias}". Give each metric one canonical name.`, context));
+        }
+        else {
+            metricAliasesByName.set(metric.name, alias);
+        }
+        if (metric.kind !== "counter" &&
+            metric.kind !== "histogram" &&
+            metric.kind !== "observable_gauge") {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_KIND", `Metric "${metricName}" has an invalid kind. Use counter, histogram, or observable_gauge.`, context));
+        }
+        if (!isValidMetricDescription(metric.description)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_DESCRIPTION", `Metric "${metric.name}" has an invalid description. Use 1 to 1024 characters without control characters.`, context));
+        }
+        if (!isValidMetricUnit(metric.unit)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_UNIT", `Metric "${metric.name}" has an invalid unit. Use the runtime unit grammar and at most 63 characters.`, context));
+        }
+        if ((metric.kind === "histogram" &&
+            (metric.boundaries === undefined || !isValidHistogramBoundaries(metric.boundaries))) ||
+            (metric.kind !== "histogram" && metric.boundaries !== undefined)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_BOUNDARIES", `Metric "${metric.name}" has invalid boundaries. Histograms require 1 to 50 sorted finite boundaries and other kinds reject boundaries.`, context));
+        }
+        if (!isValidMetricAttributeCount(Object.keys(metric.attributes).length)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION", `Metric "${metric.name}" exceeds the runtime ceiling of 16 attributes. Remove attributes before compiling.`, context));
+        }
+        for (const [attributeName, attribute] of Object.entries(metric.attributes)) {
+            const attributeContext = { ...context, attributeName };
+            if (!isValidMetricAttributeName(attributeName)) {
+                issues.push(issue("OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_NAME", `Metric attribute "${attributeName}" is invalid. Use a dotted lowercase name no longer than 128 characters.`, attributeContext));
+            }
+            if (attribute.classification !== "public" && attribute.classification !== "internal") {
+                issues.push(issue("OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION", `Metric attribute "${attributeName}" has an invalid classification. Use public or internal; sensitive and forbidden attributes cannot be metric labels.`, attributeContext));
+            }
+            if (!isValidMetricCardinality(attribute.maximumCardinality)) {
+                issues.push(issue("OBS_CONTRACT_INVALID_METRIC_CARDINALITY", `Metric attribute "${attributeName}" has invalid maximumCardinality. Use an integer from 1 through 100.`, attributeContext));
+            }
+            if (!validAllowedValues(attribute.allowedValues, attribute.maximumCardinality)) {
+                issues.push(issue("OBS_CONTRACT_INVALID_METRIC_ALLOWED_VALUES", `Metric attribute "${attributeName}" has invalid allowedValues. Use a non-empty unique scalar list no larger than maximumCardinality.`, attributeContext));
+            }
+        }
+    }
+    for (const [alias, action] of Object.entries(definition.auditActions)) {
+        const existingAlias = auditActionAliasesByName.get(action.action);
+        if (existingAlias !== undefined) {
+            issues.push(issue("OBS_CONTRACT_DUPLICATE_AUDIT_ACTION", `Audit action "${action.action}" is declared by aliases "${existingAlias}" and "${alias}". Give each audit action one canonical name.`, { auditActionAlias: alias, auditActionName: action.action }));
+        }
+        else {
+            auditActionAliasesByName.set(action.action, alias);
+        }
+        const actionContext = { auditActionAlias: alias, auditActionName: action.action };
+        if (!isAuditAction(action.action)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_AUDIT_ACTION", `Audit action alias "${alias}" has an invalid canonical action. Use 3 to 128 characters in dotted lowercase form with at least two segments.`, actionContext));
+        }
+        if (!isAuditResourceType(action.resourceType)) {
+            issues.push(issue("OBS_CONTRACT_INVALID_AUDIT_ACTION", `Audit action "${action.action}" has an invalid resourceType. Use 1 to 64 characters without control characters, starting each dot-separated segment with a lowercase letter and continuing with lowercase letters, digits, or underscores.`, actionContext));
+        }
+        if (action.allowedOutcomes.length === 0 ||
+            action.allowedOutcomes.some((outcome) => !isAuditOutcome(outcome))) {
+            issues.push(issue("OBS_CONTRACT_INVALID_AUDIT_ACTION", `Audit action "${action.action}" has invalid allowedOutcomes. Use a non-empty list containing only success, failure, cancelled, or denied.`, actionContext));
+        }
+        const reasonCodes = action.reasonCodes ?? [];
+        const seenReasonCodes = new Set();
+        for (const reasonCode of reasonCodes) {
+            if (!isAuditReasonCode(reasonCode) || seenReasonCodes.has(reasonCode)) {
+                issues.push(issue("OBS_CONTRACT_INVALID_AUDIT_REASON_CODE", `Audit action "${action.action}" has malformed or duplicate reason code "${reasonCode}". Use unique dotted lowercase codes no longer than 64 characters.`, { auditActionAlias: alias, auditActionName: action.action }));
+            }
+            seenReasonCodes.add(reasonCode);
+        }
+    }
+    return issues;
+};
+export const defineTelemetryContract = Effect.fn("defineTelemetryContract")(function* (definition) {
+    const documentIsInvalid = yield* decodeTelemetryContractDocument(definition).pipe(Effect.match({ onFailure: () => true, onSuccess: () => false }));
+    if (documentIsInvalid) {
+        return yield* new InvalidTelemetryContract({
+            code: "OBS_CONTRACT_INVALID",
+            message: "Telemetry contract has an invalid outer document. Provide version, events, metrics, and auditActions records.",
+            issues: [
+                issue("OBS_CONTRACT_INVALID_DOCUMENT", "Telemetry contract document is malformed. Provide version, events, metrics, and auditActions records."),
+            ],
+        });
+    }
+    const issues = collectIssues(definition);
+    if (issues.length > 0) {
+        return yield* new InvalidTelemetryContract({
+            code: "OBS_CONTRACT_INVALID",
+            message: `Telemetry contract compilation failed with ${issues.length} issue(s). Fix every reported issue and compile again.`,
+            issues,
+        });
+    }
+    const compiledDefinition = freezeTelemetryContractDefinition(structuredClone(definition));
+    const provenance = canonicalTelemetryContractProvenance(compiledDefinition);
+    const eventNames = [];
+    const mutableEventByAlias = new Map();
+    const mutableEventByName = new Map();
+    for (const [alias, event] of Object.entries(compiledDefinition.events)) {
+        const name = EventName.make(event.name);
+        const compiled = Object.freeze({
+            alias,
+            name,
+            kind: event.kind,
+            defaultSeverity: event.defaultSeverity,
+            mandatory: event.mandatory,
+            sampling: event.sampling,
+            attributes: immutableMap(Object.entries(event.attributes)),
+            requiredAttributes: Object.freeze(Object.entries(event.attributes)
+                .filter((entry) => entry[1].required)
+                .map((entry) => entry[0])),
+        });
+        eventNames.push(name);
+        mutableEventByAlias.set(alias, compiled);
+        mutableEventByName.set(name, compiled);
+    }
+    const mutableAuditActionByAlias = new Map();
+    const mutableAuditActionByName = new Map();
+    for (const [alias, action] of Object.entries(compiledDefinition.auditActions)) {
+        const compiled = Object.freeze({
+            alias,
+            action: AuditAction.make(action.action),
+            resourceType: action.resourceType,
+            allowedOutcomes: action.allowedOutcomes,
+            reasonCodes: action.reasonCodes ?? Object.freeze([]),
+        });
+        mutableAuditActionByAlias.set(alias, compiled);
+        mutableAuditActionByName.set(action.action, compiled);
+    }
+    const mutableMetricByAlias = new Map();
+    const mutableMetricByName = new Map();
+    for (const [alias, metric] of Object.entries(compiledDefinition.metrics)) {
+        const compiled = Object.freeze({
+            ...metric,
+            alias,
+            attributes: immutableMap(Object.entries(metric.attributes)),
+        });
+        mutableMetricByAlias.set(alias, compiled);
+        mutableMetricByName.set(metric.name, compiled);
+    }
+    return Object.freeze({
+        version: compiledDefinition.version,
+        definition: compiledDefinition,
+        provenance,
+        eventNames: Object.freeze(eventNames),
+        eventByAlias: immutableMap(mutableEventByAlias),
+        eventByName: immutableMap(mutableEventByName),
+        auditActionByAlias: immutableMap(mutableAuditActionByAlias),
+        auditActionByName: immutableMap(mutableAuditActionByName),
+        metrics: compiledDefinition.metrics,
+        metricByAlias: immutableMap(mutableMetricByAlias),
+        metricByName: immutableMap(mutableMetricByName),
+    });
+});

package/dist/contract/TelemetryContractError.d.ts

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+export declare const ContractIssueCode: Schema.Literals<readonly ["OBS_CONTRACT_INVALID_DOCUMENT", "OBS_CONTRACT_INVALID_VERSION", "OBS_CONTRACT_INVALID_EVENT_NAME", "OBS_CONTRACT_DUPLICATE_EVENT_NAME", "OBS_CONTRACT_INVALID_EVENT_KIND", "OBS_CONTRACT_INVALID_DEFAULT_SEVERITY", "OBS_CONTRACT_INVALID_ATTRIBUTE_NAME", "OBS_CONTRACT_RESERVED_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_SAMPLING_RATE", "OBS_CONTRACT_INVALID_AUDIT_ACTION", "OBS_CONTRACT_DUPLICATE_AUDIT_ACTION", "OBS_CONTRACT_INVALID_AUDIT_REASON_CODE", "OBS_CONTRACT_INVALID_METRIC_NAME", "OBS_CONTRACT_DUPLICATE_METRIC_NAME", "OBS_CONTRACT_INVALID_METRIC_KIND", "OBS_CONTRACT_INVALID_METRIC_UNIT", "OBS_CONTRACT_INVALID_METRIC_DESCRIPTION", "OBS_CONTRACT_INVALID_METRIC_BOUNDARIES", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_METRIC_ALLOWED_VALUES", "OBS_CONTRACT_INVALID_METRIC_CARDINALITY"]>;
+export type ContractIssueCode = typeof ContractIssueCode.Type;
+export declare const ContractIssue: Schema.Struct<{
+    readonly code: Schema.Literals<readonly ["OBS_CONTRACT_INVALID_DOCUMENT", "OBS_CONTRACT_INVALID_VERSION", "OBS_CONTRACT_INVALID_EVENT_NAME", "OBS_CONTRACT_DUPLICATE_EVENT_NAME", "OBS_CONTRACT_INVALID_EVENT_KIND", "OBS_CONTRACT_INVALID_DEFAULT_SEVERITY", "OBS_CONTRACT_INVALID_ATTRIBUTE_NAME", "OBS_CONTRACT_RESERVED_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_SAMPLING_RATE", "OBS_CONTRACT_INVALID_AUDIT_ACTION", "OBS_CONTRACT_DUPLICATE_AUDIT_ACTION", "OBS_CONTRACT_INVALID_AUDIT_REASON_CODE", "OBS_CONTRACT_INVALID_METRIC_NAME", "OBS_CONTRACT_DUPLICATE_METRIC_NAME", "OBS_CONTRACT_INVALID_METRIC_KIND", "OBS_CONTRACT_INVALID_METRIC_UNIT", "OBS_CONTRACT_INVALID_METRIC_DESCRIPTION", "OBS_CONTRACT_INVALID_METRIC_BOUNDARIES", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_METRIC_ALLOWED_VALUES", "OBS_CONTRACT_INVALID_METRIC_CARDINALITY"]>;
+    readonly message: Schema.String;
+    readonly eventAlias: Schema.optionalKey<Schema.String>;
+    readonly eventName: Schema.optionalKey<Schema.String>;
+    readonly attributeName: Schema.optionalKey<Schema.String>;
+    readonly auditActionAlias: Schema.optionalKey<Schema.String>;
+    readonly auditActionName: Schema.optionalKey<Schema.String>;
+    readonly metricAlias: Schema.optionalKey<Schema.String>;
+    readonly metricName: Schema.optionalKey<Schema.String>;
+}>;
+export type ContractIssue = typeof ContractIssue.Type;
+declare const InvalidTelemetryContract_base: Schema.Class<InvalidTelemetryContract, Schema.TaggedStruct<"InvalidTelemetryContract", {
+    readonly code: Schema.Literal<"OBS_CONTRACT_INVALID">;
+    readonly message: Schema.String;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly code: Schema.Literals<readonly ["OBS_CONTRACT_INVALID_DOCUMENT", "OBS_CONTRACT_INVALID_VERSION", "OBS_CONTRACT_INVALID_EVENT_NAME", "OBS_CONTRACT_DUPLICATE_EVENT_NAME", "OBS_CONTRACT_INVALID_EVENT_KIND", "OBS_CONTRACT_INVALID_DEFAULT_SEVERITY", "OBS_CONTRACT_INVALID_ATTRIBUTE_NAME", "OBS_CONTRACT_RESERVED_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_SAMPLING_RATE", "OBS_CONTRACT_INVALID_AUDIT_ACTION", "OBS_CONTRACT_DUPLICATE_AUDIT_ACTION", "OBS_CONTRACT_INVALID_AUDIT_REASON_CODE", "OBS_CONTRACT_INVALID_METRIC_NAME", "OBS_CONTRACT_DUPLICATE_METRIC_NAME", "OBS_CONTRACT_INVALID_METRIC_KIND", "OBS_CONTRACT_INVALID_METRIC_UNIT", "OBS_CONTRACT_INVALID_METRIC_DESCRIPTION", "OBS_CONTRACT_INVALID_METRIC_BOUNDARIES", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_NAME", "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION", "OBS_CONTRACT_INVALID_METRIC_ALLOWED_VALUES", "OBS_CONTRACT_INVALID_METRIC_CARDINALITY"]>;
+        readonly message: Schema.String;
+        readonly eventAlias: Schema.optionalKey<Schema.String>;
+        readonly eventName: Schema.optionalKey<Schema.String>;
+        readonly attributeName: Schema.optionalKey<Schema.String>;
+        readonly auditActionAlias: Schema.optionalKey<Schema.String>;
+        readonly auditActionName: Schema.optionalKey<Schema.String>;
+        readonly metricAlias: Schema.optionalKey<Schema.String>;
+        readonly metricName: Schema.optionalKey<Schema.String>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidTelemetryContract extends InvalidTelemetryContract_base {
+}
+export declare const TelemetryEventErrorCode: Schema.Literals<readonly ["OBS_EVENT_UNKNOWN_NAME", "OBS_EVENT_UNDECLARED_ATTRIBUTE", "OBS_EVENT_MISSING_ATTRIBUTE", "OBS_EVENT_INVALID_FIELD", "OBS_EVENT_INVALID_OUTCOME", "OBS_EVENT_RESTRICTED_ATTRIBUTE", "OBS_EVENT_SENSITIVE_METRIC_LABEL", "OBS_EVENT_UNKNOWN_AUDIT_ACTION", "OBS_EVENT_INVALID_AUDIT_RESOURCE", "OBS_EVENT_INVALID_AUDIT_OUTCOME", "OBS_EVENT_INVALID_AUDIT_REASON"]>;
+export type TelemetryEventErrorCode = typeof TelemetryEventErrorCode.Type;
+declare const InvalidTelemetryEvent_base: Schema.Class<InvalidTelemetryEvent, Schema.TaggedStruct<"InvalidTelemetryEvent", {
+    readonly code: Schema.Literals<readonly ["OBS_EVENT_UNKNOWN_NAME", "OBS_EVENT_UNDECLARED_ATTRIBUTE", "OBS_EVENT_MISSING_ATTRIBUTE", "OBS_EVENT_INVALID_FIELD", "OBS_EVENT_INVALID_OUTCOME", "OBS_EVENT_RESTRICTED_ATTRIBUTE", "OBS_EVENT_SENSITIVE_METRIC_LABEL", "OBS_EVENT_UNKNOWN_AUDIT_ACTION", "OBS_EVENT_INVALID_AUDIT_RESOURCE", "OBS_EVENT_INVALID_AUDIT_OUTCOME", "OBS_EVENT_INVALID_AUDIT_REASON"]>;
+    readonly message: Schema.String;
+    readonly eventName: Schema.optionalKey<Schema.String>;
+    readonly eventAlias: Schema.optionalKey<Schema.String>;
+    readonly attributeName: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class InvalidTelemetryEvent extends InvalidTelemetryEvent_base {
+}
+export {};

package/dist/contract/TelemetryContractError.js

@@ -0,0 +1,64 @@
+import { Schema } from "effect";
+export const ContractIssueCode = Schema.Literals([
+    "OBS_CONTRACT_INVALID_DOCUMENT",
+    "OBS_CONTRACT_INVALID_VERSION",
+    "OBS_CONTRACT_INVALID_EVENT_NAME",
+    "OBS_CONTRACT_DUPLICATE_EVENT_NAME",
+    "OBS_CONTRACT_INVALID_EVENT_KIND",
+    "OBS_CONTRACT_INVALID_DEFAULT_SEVERITY",
+    "OBS_CONTRACT_INVALID_ATTRIBUTE_NAME",
+    "OBS_CONTRACT_RESERVED_ATTRIBUTE_NAME",
+    "OBS_CONTRACT_INVALID_ATTRIBUTE_DEFINITION",
+    "OBS_CONTRACT_INVALID_SAMPLING_RATE",
+    "OBS_CONTRACT_INVALID_AUDIT_ACTION",
+    "OBS_CONTRACT_DUPLICATE_AUDIT_ACTION",
+    "OBS_CONTRACT_INVALID_AUDIT_REASON_CODE",
+    "OBS_CONTRACT_INVALID_METRIC_NAME",
+    "OBS_CONTRACT_DUPLICATE_METRIC_NAME",
+    "OBS_CONTRACT_INVALID_METRIC_KIND",
+    "OBS_CONTRACT_INVALID_METRIC_UNIT",
+    "OBS_CONTRACT_INVALID_METRIC_DESCRIPTION",
+    "OBS_CONTRACT_INVALID_METRIC_BOUNDARIES",
+    "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_NAME",
+    "OBS_CONTRACT_INVALID_METRIC_ATTRIBUTE_DEFINITION",
+    "OBS_CONTRACT_INVALID_METRIC_ALLOWED_VALUES",
+    "OBS_CONTRACT_INVALID_METRIC_CARDINALITY",
+]);
+export const ContractIssue = Schema.Struct({
+    code: ContractIssueCode,
+    message: Schema.String,
+    eventAlias: Schema.String.pipe(Schema.optionalKey),
+    eventName: Schema.String.pipe(Schema.optionalKey),
+    attributeName: Schema.String.pipe(Schema.optionalKey),
+    auditActionAlias: Schema.String.pipe(Schema.optionalKey),
+    auditActionName: Schema.String.pipe(Schema.optionalKey),
+    metricAlias: Schema.String.pipe(Schema.optionalKey),
+    metricName: Schema.String.pipe(Schema.optionalKey),
+});
+export class InvalidTelemetryContract extends Schema.TaggedError()("InvalidTelemetryContract", {
+    code: Schema.Literal("OBS_CONTRACT_INVALID"),
+    message: Schema.String,
+    issues: Schema.Array(ContractIssue),
+}) {
+}
+export const TelemetryEventErrorCode = Schema.Literals([
+    "OBS_EVENT_UNKNOWN_NAME",
+    "OBS_EVENT_UNDECLARED_ATTRIBUTE",
+    "OBS_EVENT_MISSING_ATTRIBUTE",
+    "OBS_EVENT_INVALID_FIELD",
+    "OBS_EVENT_INVALID_OUTCOME",
+    "OBS_EVENT_RESTRICTED_ATTRIBUTE",
+    "OBS_EVENT_SENSITIVE_METRIC_LABEL",
+    "OBS_EVENT_UNKNOWN_AUDIT_ACTION",
+    "OBS_EVENT_INVALID_AUDIT_RESOURCE",
+    "OBS_EVENT_INVALID_AUDIT_OUTCOME",
+    "OBS_EVENT_INVALID_AUDIT_REASON",
+]);
+export class InvalidTelemetryEvent extends Schema.TaggedError()("InvalidTelemetryEvent", {
+    code: TelemetryEventErrorCode,
+    message: Schema.String,
+    eventName: Schema.String.pipe(Schema.optionalKey),
+    eventAlias: Schema.String.pipe(Schema.optionalKey),
+    attributeName: Schema.String.pipe(Schema.optionalKey),
+}) {
+}

package/dist/contract/TelemetryEvent.d.ts

@@ -0,0 +1,59 @@
+import { Schema } from "effect";
+import { AuditContext, AuditOutcome } from "../audit/AuditRecord.js";
+import type { CorrelationContext } from "../Correlation.js";
+import type { EventName } from "./EventName.js";
+export declare const EventSeverity: Schema.Literals<readonly ["debug", "info", "warn", "error", "fatal"]>;
+export type EventSeverity = typeof EventSeverity.Type;
+export declare const EventOutcome: Schema.Literals<readonly ["success", "failure", "cancelled"]>;
+export type EventOutcome = typeof EventOutcome.Type;
+export declare const EventKind: Schema.Literals<readonly ["request", "operation", "domain", "defect", "audit"]>;
+export type EventKind = typeof EventKind.Type;
+export type AttributeValue = string | number | boolean;
+export type EventAttributes = {
+    readonly [attributeName: string]: AttributeValue;
+};
+export declare const HttpContext: Schema.Struct<{
+    readonly method: Schema.NonEmptyString;
+    readonly route: Schema.NonEmptyString;
+    readonly statusCode: Schema.Int;
+}>;
+export type HttpContext = typeof HttpContext.Type;
+export declare const ErrorContext: Schema.Struct<{
+    readonly type: Schema.NonEmptyString;
+    readonly message: Schema.String;
+    readonly retryable: Schema.Boolean;
+}>;
+export type ErrorContext = typeof ErrorContext.Type;
+export declare const maxOtlpUnixTimestampMillis = 18446744073709;
+export declare const EventTimestamp: Schema.brand<Schema.String, "EventTimestamp">;
+export type EventTimestamp = typeof EventTimestamp.Type;
+export declare const EventDuration: Schema.brand<Schema.Finite, "EventDuration">;
+export type EventDuration = typeof EventDuration.Type;
+export type EventBase = {
+    readonly timestamp: EventTimestamp;
+    readonly name: EventName;
+    readonly severity: EventSeverity;
+    readonly correlation: CorrelationContext;
+    readonly attributes: EventAttributes;
+};
+export type TelemetryEvent = (EventBase & {
+    readonly kind: "request";
+    readonly outcome: EventOutcome;
+    readonly durationMs: EventDuration;
+    readonly http: HttpContext;
+}) | (EventBase & {
+    readonly kind: "operation";
+    readonly outcome: EventOutcome;
+    readonly durationMs: EventDuration;
+}) | (EventBase & {
+    readonly kind: "domain";
+    readonly outcome: EventOutcome;
+}) | (EventBase & {
+    readonly kind: "defect";
+    readonly outcome: "failure";
+    readonly error: ErrorContext;
+}) | (EventBase & {
+    readonly kind: "audit";
+    readonly outcome: AuditOutcome;
+    readonly audit: AuditContext;
+});