@equipe-tech/observability 0.2.1 → 0.3.5

package/dist/MetricsRuntime.js

@@ -1,22 +1,18 @@
-import { Context, Effect, Layer, Metric, Predicate, Schema } from "effect";
+import { Context, Effect, Layer, Metric, Option, Predicate, Result, Schema } from "effect";
 import { HttpBody, HttpClient, HttpClientRequest } from "effect/unstable/http";
 import { OtlpExporter } from "effect/unstable/observability";
 import { MetricsError } from "./Metrics.js";
-const instrumentNamePattern = /^[A-Za-z][A-Za-z0-9_.\-/]{0,254}$/;
-const unitPattern = /^(?:1|%|[A-Za-z][A-Za-z0-9]*(?:[./*^][A-Za-z0-9]+)*)$/;
-const containsControlCharacter = (value) => {
-    for (const character of value) {
-        const codePoint = character.codePointAt(0);
-        if (codePoint !== undefined && (codePoint <= 31 || codePoint === 127)) {
-            return true;
-        }
-    }
-    return false;
-};
+import { InvalidMetricMeasurement } from "./contract/MetricContractError.js";
+import { EnvironmentAliasPolicy as EnvironmentAliasPolicySchema, parseResourceIdentity, serviceResourceAttributes, } from "./ResourceIdentity.js";
+import { baseDataPolicy } from "./policy/DataPolicy.js";
+import { metricLabelRejection } from "./policy/MetricLabelPolicy.js";
+import { isFiniteMetricScalar, metricScalarIdentity } from "./metrics/MetricScalar.js";
+import { containsControlCharacter, instrumentNamePattern, maximumMetricAttributeCardinality, maximumMetricAttributes, unitPattern, } from "./metrics/InstrumentGrammar.js";
 const maximumInstruments = 100;
 const maximumInstrumentSeries = 1_000;
+const maximumAttributeCardinality = maximumMetricAttributeCardinality;
 const maximumRuntimeSeries = 10_000;
-const maximumAttributes = 16;
+const maximumAttributes = maximumMetricAttributes;
 const maximumCallbacks = 16;
 const maximumObservations = 100;
 const MetricAttributeInput = Schema.Struct({
@@ -44,6 +40,7 @@ const MetricsOptionsInput = Schema.Struct({
     serviceName: Schema.String,
     serviceVersion: Schema.String,
     environment: Schema.String,
+    deploymentEnvironmentAlias: EnvironmentAliasPolicySchema.pipe(Schema.optionalKey),
     otlpEndpoint: Schema.String,
     exportIntervalMilliseconds: Schema.Number.pipe(Schema.optionalKey),
     flushTimeoutMilliseconds: Schema.Number.pipe(Schema.optionalKey),
@@ -53,20 +50,26 @@ const decodeInstrumentDefinition = Schema.decodeUnknownSync(InstrumentDefinition
 const decodeHistogramDefinition = Schema.decodeUnknownSync(HistogramDefinitionInput);
 const decodeGaugeObservations = Schema.decodeUnknownSync(GaugeObservationsInput);
 const decodeMetricsOptions = Schema.decodeUnknownSync(MetricsOptionsInput);
-const metricError = (code, operation, message, instrumentName, retryable, cause) => {
-    const options = {
-        code,
-        operation,
-        message,
-        retryable,
-        cause,
-    };
+const gaugeObservationContracts = new WeakMap();
+export const registerContractGaugeObservation = (observation, contract) => {
+    gaugeObservationContracts.set(observation, contract);
+    return observation;
+};
+const metricError = (code, operation, message, instrumentName, retryable, cause, attributeKey, policyReason) => {
+    const options = { code, operation, message, retryable };
+    if (cause !== undefined)
+        options.cause = cause;
+    if (attributeKey !== undefined)
+        options.attributeKey = attributeKey;
+    if (policyReason !== undefined)
+        options.policyReason = policyReason;
     if (instrumentName === undefined) {
         return new MetricsError(options);
     }
     return new MetricsError({ ...options, instrumentName });
 };
 const parseOptions = (input) => {
+    const policy = input.policy ?? baseDataPolicy;
     let options;
     try {
         options = decodeMetricsOptions(input);
@@ -74,11 +77,25 @@ const parseOptions = (input) => {
     catch (cause) {
         throw metricError("INVALID_CONFIGURATION", "createMetrics", "Metrics configuration is invalid. Provide valid service metadata and an HTTP OTLP endpoint.", undefined, false, cause);
     }
-    if (options.serviceName.length === 0 ||
-        options.serviceVersion.length === 0 ||
-        options.environment.length === 0) {
-        throw metricError("INVALID_CONFIGURATION", "createMetrics", "Metrics configuration is invalid. Service name, version, and environment must be nonempty.", undefined, false);
+    const parsedIdentity = Effect.runSync(Effect.result(parseResourceIdentity({
+        serviceName: options.serviceName,
+        serviceVersion: options.serviceVersion,
+        environment: options.environment,
+        instance: Option.none(),
+    })));
+    if (Result.isFailure(parsedIdentity)) {
+        const failure = parsedIdentity.failure;
+        throw new MetricsError({
+            code: "INVALID_CONFIGURATION",
+            operation: "createMetrics",
+            message: failure.message,
+            field: failure.field,
+            rule: failure.rule,
+            retryable: false,
+            cause: failure,
+        });
     }
+    const identity = parsedIdentity.success;
     let endpoint;
     try {
         endpoint = new URL(options.otlpEndpoint);
@@ -103,23 +120,31 @@ const parseOptions = (input) => {
     endpoint.search = "";
     endpoint.hash = "";
     const enabled = options.enabled ?? true;
+    const policyKey = JSON.stringify([
+        Array.from(policy.attributes.entries()),
+        policy.blockedKeys.map((pattern) => [pattern.source, pattern.flags]),
+        policy.blockedValuePatterns.map((pattern) => [pattern.source, pattern.flags]),
+    ]);
+    const environmentAlias = options.deploymentEnvironmentAlias ?? "omitted";
     const poolKey = JSON.stringify([
         endpoint.toString(),
         options.serviceName,
         options.serviceVersion,
         options.environment,
+        options.deploymentEnvironmentAlias ?? "omitted",
         exportIntervalMilliseconds,
         flushTimeoutMilliseconds,
+        policyKey,
     ]);
     return {
         enabled,
-        serviceName: options.serviceName,
-        serviceVersion: options.serviceVersion,
-        environment: options.environment,
+        identity,
         metricsEndpoint: endpoint.toString(),
         exportIntervalMilliseconds,
         flushTimeoutMilliseconds,
         poolKey,
+        policy,
+        resourceAttributes: new Map(Object.entries(serviceResourceAttributes(identity, environmentAlias))),
     };
 };
 const parseDefinition = (input, operation) => {
@@ -161,16 +186,7 @@ const parseHistogramDefinition = (input) => {
     }
     return { ...common, boundaries: [...definition.boundaries] };
 };
-const attributeIdentity = (value) => {
-    if (Predicate.isString(value)) {
-        return `s:${JSON.stringify(value)}`;
-    }
-    if (Predicate.isBoolean(value)) {
-        return value ? "b:1" : "b:0";
-    }
-    return `n:${Object.is(value, -0) ? 0 : value}`;
-};
-const parseAttributes = (input, operation, instrumentName) => {
+const parseAttributes = (input, operation, instrumentName, policy) => {
     let attributes;
     try {
         attributes = decodeMetricAttributes(input ?? []);
@@ -184,18 +200,19 @@ const parseAttributes = (input, operation, instrumentName) => {
     const keys = new Set();
     const normalized = [];
     for (const attribute of attributes) {
-        const numberIsInvalid = Predicate.isNumber(attribute.value) && !Number.isFinite(attribute.value);
-        const stringIsInvalid = Predicate.isString(attribute.value) &&
-            (attribute.value.length > 256 || containsControlCharacter(attribute.value));
         if (attribute.key.length > 128 ||
             !instrumentNamePattern.test(attribute.key) ||
             attribute.key === "unit" ||
             attribute.key === "time_unit" ||
+            attribute.key === "service.instance.id" ||
             keys.has(attribute.key) ||
-            numberIsInvalid ||
-            stringIsInvalid) {
+            !isFiniteMetricScalar(attribute.value)) {
             throw metricError("INVALID_MEASUREMENT", operation, `Metric "${instrumentName}" attributes are invalid. Use unique bounded keys and finite scalar values.`, instrumentName, false);
         }
+        const rejection = metricLabelRejection(policy, attribute.key, attribute.value);
+        if (rejection !== undefined) {
+            throw metricError("POLICY_BLOCKED", operation, `Metric "${instrumentName}" contains a label blocked by the data policy. Remove the label before recording.`, instrumentName, false, undefined, undefined, rejection);
+        }
         keys.add(attribute.key);
         normalized.push({
             key: attribute.key,
@@ -205,7 +222,7 @@ const parseAttributes = (input, operation, instrumentName) => {
     normalized.sort((left, right) => left.key.localeCompare(right.key));
     return {
         identity: normalized
-            .map((attribute) => `${attribute.key}=${attributeIdentity(attribute.value)}`)
+            .map((attribute) => `${attribute.key}=${metricScalarIdentity(attribute.value)}`)
             .join("|"),
         values: normalized,
     };
@@ -222,17 +239,31 @@ const attributesToOtlp = (attributes) => attributes.map((attribute) => {
     }
     return { key: attribute.key, value: { doubleValue: attribute.value } };
 });
-const directAttributesToOtlp = (attributes) => {
+const directAttributesToOtlp = (attributes, instrumentName, policy) => {
     if (attributes === undefined) {
-        return [];
+        return { values: [], failures: [] };
     }
     const values = [];
+    const failures = [];
     for (const [key, value] of Object.entries(attributes)) {
-        if (key !== "unit" && key !== "time_unit") {
-            values.push({ key, value: { stringValue: value } });
+        if (key === "unit" || key === "time_unit")
+            continue;
+        if (key === "service.instance.id") {
+            throw metricError("EXPORT_FAILED", "flush", `Metric "${instrumentName}" cannot use service.instance.id as a datapoint attribute. Remove the reserved key before retrying.`, instrumentName, false);
         }
+        const rejection = metricLabelRejection(policy, key, value);
+        if (rejection !== undefined) {
+            failures.push({
+                instrumentName,
+                code: "POLICY_BLOCKED",
+                message: `Metric "${instrumentName}" dropped a label blocked by the data policy.`,
+                policyReason: rejection,
+            });
+            continue;
+        }
+        values.push({ key, value: { stringValue: value } });
     }
-    return values;
+    return { values, failures };
 };
 const sameDefinition = (entry, kind, definition, boundaries) => {
     if (entry.kind !== kind ||
@@ -261,10 +292,13 @@ const histogramBucketIndex = (boundaries, value) => {
 const nanosNow = () => String(BigInt(Date.now()) * 1000000n);
 class MetricsRuntimeState {
     registry = new Map();
+    policy;
     directContext = Context.make(Metric.MetricRegistry, this.registry);
     catalog = new Map();
     runtimeLifetimeSeries = new Set();
     lifetimeSeriesByInstrument = new Map();
+    lifetimeValuesByInstrumentKey = new Map();
+    contractValuesByDefinition = new WeakMap();
     lifetimeInstrumentNames = new Set();
     leases = new Set();
     transports = new Map();
@@ -279,6 +313,7 @@ class MetricsRuntimeState {
     periodicFailureActive = false;
     constructor(options, removeFromPool) {
         this.options = options;
+        this.policy = options.policy;
         this.removeFromPool = removeFromPool;
         this.timer = setInterval(() => {
             this.scheduleExport(this.options.flushTimeoutMilliseconds).then((result) => this.recordPeriodicOutcome(result.gaugeFailures.length > 0), () => this.recordPeriodicOutcome(true));
@@ -298,18 +333,19 @@ class MetricsRuntimeState {
     flush(timeoutMilliseconds) {
         return this.scheduleExport(timeoutMilliseconds);
     }
-    async closeLease(leaseId, timeoutMilliseconds) {
-        let result;
+    async closeLease(leaseId, timeoutMilliseconds, exportBeforeClose = true) {
+        let result = { gaugeFailures: [] };
         let failure;
-        try {
-            result = await this.scheduleExport(timeoutMilliseconds);
-        }
-        catch (cause) {
-            result = { gaugeFailures: [] };
-            failure =
-                cause instanceof MetricsError
-                    ? cause
-                    : metricError("EXPORT_FAILED", "close", "The final metrics export failed. The runtime lease was still released.", undefined, true, cause);
+        if (exportBeforeClose) {
+            try {
+                result = await this.scheduleExport(timeoutMilliseconds);
+            }
+            catch (cause) {
+                failure =
+                    cause instanceof MetricsError
+                        ? cause
+                        : metricError("EXPORT_FAILED", "close", "The final metrics export failed. The runtime lease was still released.", undefined, true, cause);
+            }
         }
         this.removeLeaseState(leaseId);
         this.leases.delete(leaseId);
@@ -417,25 +453,137 @@ class MetricsRuntimeState {
             this.catalog.delete(name);
         }
     }
-    addCounter(leaseId, entry, value, attributes) {
+    prepareCounter(leaseId, entry, value, attributes) {
         this.assertLease(leaseId, "add", entry.definition.name);
         if (!Number.isFinite(value) || value < 0) {
             throw metricError("INVALID_MEASUREMENT", "add", `Counter "${entry.definition.name}" accepts only finite values greater than or equal to zero.`, entry.definition.name, false);
         }
         this.prepareSeries(entry, attributes, "add");
-        let leaseSeries = entry.seriesByLease.get(leaseId);
-        if (leaseSeries === undefined) {
-            leaseSeries = new Map();
-            entry.seriesByLease.set(leaseId, leaseSeries);
-        }
-        const current = leaseSeries.get(attributes.identity);
-        if (current === undefined) {
-            leaseSeries.set(attributes.identity, { attributes, value });
-            this.commitSeries(entry, attributes.identity);
+        return () => {
+            let leaseSeries = entry.seriesByLease.get(leaseId);
+            if (leaseSeries === undefined) {
+                leaseSeries = new Map();
+                entry.seriesByLease.set(leaseId, leaseSeries);
+            }
+            const current = leaseSeries.get(attributes.identity);
+            if (current === undefined) {
+                leaseSeries.set(attributes.identity, { attributes, value });
+                this.commitSeries(entry, attributes);
+            }
+            else {
+                current.value += value;
+            }
+        };
+    }
+    reserveCounterBatch(leaseId, measurements) {
+        const projectedInstrumentNames = new Set(this.lifetimeInstrumentNames);
+        const projectedRuntimeSeries = new Set(this.runtimeLifetimeSeries);
+        const projectedSeriesByInstrument = new Map();
+        const projectedValuesByInstrumentKey = new Map();
+        const entries = new Map();
+        const prepared = [];
+        for (const measurement of measurements) {
+            this.assertLease(leaseId, "add", measurement.definition.name);
+            let entry = entries.get(measurement.definition.name);
+            if (entry === undefined) {
+                const existing = this.catalog.get(measurement.definition.name);
+                if (existing !== undefined) {
+                    if (existing.kind !== "counter" ||
+                        !sameDefinition(existing, "counter", measurement.definition, undefined)) {
+                        throw this.instrumentConflict("counter", measurement.definition.name);
+                    }
+                    entry = existing;
+                }
+                else {
+                    if (!projectedInstrumentNames.has(measurement.definition.name)) {
+                        if (projectedInstrumentNames.size >= maximumInstruments) {
+                            throw metricError("LIMIT_EXCEEDED", "registerInstrument", `Metric runtime exceeds the ${maximumInstruments}-instrument lifetime limit while registering "${measurement.definition.name}".`, measurement.definition.name, false);
+                        }
+                        projectedInstrumentNames.add(measurement.definition.name);
+                    }
+                    entry = {
+                        kind: "counter",
+                        definition: measurement.definition,
+                        leases: new Set(),
+                        residualSeries: new Map(),
+                        seriesByLease: new Map(),
+                        lifetimeSeries: this.lifetimeSeriesByInstrument.get(measurement.definition.name) ?? new Set(),
+                    };
+                }
+                entries.set(measurement.definition.name, entry);
+            }
+            else if (!sameDefinition(entry, "counter", measurement.definition, undefined)) {
+                throw this.instrumentConflict("counter", measurement.definition.name);
+            }
+            if (!Number.isFinite(measurement.value) || measurement.value < 0) {
+                throw metricError("INVALID_MEASUREMENT", "add", `Counter "${entry.definition.name}" accepts only finite values greater than or equal to zero.`, entry.definition.name, false);
+            }
+            for (const attribute of measurement.attributes.values) {
+                const key = `${entry.definition.name}:${attribute.key}`;
+                let values = projectedValuesByInstrumentKey.get(key);
+                if (values === undefined) {
+                    values = new Set(this.lifetimeValuesByInstrumentKey.get(key));
+                    projectedValuesByInstrumentKey.set(key, values);
+                }
+                const identity = metricScalarIdentity(attribute.value);
+                if (!values.has(identity) && values.size >= maximumAttributeCardinality) {
+                    throw metricError("LIMIT_EXCEEDED", "add", `Metric "${entry.definition.name}" exceeds the ${maximumAttributeCardinality}-value lifetime limit for one label.`, entry.definition.name, false, undefined, attribute.key);
+                }
+                values.add(identity);
+            }
+            let series = projectedSeriesByInstrument.get(entry.definition.name);
+            if (series === undefined) {
+                series = new Set(entry.lifetimeSeries);
+                projectedSeriesByInstrument.set(entry.definition.name, series);
+            }
+            if (!series.has(measurement.attributes.identity)) {
+                if (series.size >= maximumInstrumentSeries) {
+                    throw metricError("LIMIT_EXCEEDED", "add", `Metric "${entry.definition.name}" exceeds the ${maximumInstrumentSeries}-series lifetime limit.`, entry.definition.name, false);
+                }
+                series.add(measurement.attributes.identity);
+            }
+            const runtimeIdentity = `${entry.definition.name}:${measurement.attributes.identity}`;
+            if (!projectedRuntimeSeries.has(runtimeIdentity)) {
+                if (projectedRuntimeSeries.size >= maximumRuntimeSeries) {
+                    throw metricError("LIMIT_EXCEEDED", "add", `Metric runtime exceeds the ${maximumRuntimeSeries}-series lifetime limit.`, entry.definition.name, false);
+                }
+                projectedRuntimeSeries.add(runtimeIdentity);
+            }
+            prepared.push({ entry, value: measurement.value, attributes: measurement.attributes });
         }
-        else {
-            current.value += value;
+        for (const [name, entry] of entries) {
+            this.lifetimeInstrumentNames.add(name);
+            entry.leases.add(leaseId);
+            if (!this.lifetimeSeriesByInstrument.has(name)) {
+                this.lifetimeSeriesByInstrument.set(name, entry.lifetimeSeries);
+            }
+            if (!this.catalog.has(name))
+                this.catalog.set(name, entry);
         }
+        for (const measurement of prepared)
+            this.commitSeries(measurement.entry, measurement.attributes);
+        return () => {
+            for (const measurement of prepared) {
+                let leaseSeries = measurement.entry.seriesByLease.get(leaseId);
+                if (leaseSeries === undefined) {
+                    leaseSeries = new Map();
+                    measurement.entry.seriesByLease.set(leaseId, leaseSeries);
+                }
+                const current = leaseSeries.get(measurement.attributes.identity);
+                if (current === undefined) {
+                    leaseSeries.set(measurement.attributes.identity, {
+                        attributes: measurement.attributes,
+                        value: measurement.value,
+                    });
+                }
+                else {
+                    current.value += measurement.value;
+                }
+            }
+        };
+    }
+    addCounter(leaseId, entry, value, attributes) {
+        this.prepareCounter(leaseId, entry, value, attributes)();
     }
     recordHistogram(leaseId, entry, value, attributes) {
         this.assertLease(leaseId, "record", entry.definition.name);
@@ -461,7 +609,7 @@ class MetricsRuntimeState {
                 max: value,
                 bucketCounts,
             });
-            this.commitSeries(entry, attributes.identity);
+            this.commitSeries(entry, attributes);
         }
         else {
             current.count++;
@@ -509,6 +657,16 @@ class MetricsRuntimeState {
     }
     prepareSeries(entry, attributes, operation) {
         const runtimeIdentity = `${entry.definition.name}:${attributes.identity}`;
+        for (const attribute of attributes.values) {
+            const key = `${entry.definition.name}:${attribute.key}`;
+            const values = this.lifetimeValuesByInstrumentKey.get(key);
+            const identity = metricScalarIdentity(attribute.value);
+            if (values !== undefined &&
+                !values.has(identity) &&
+                values.size >= maximumAttributeCardinality) {
+                throw metricError("LIMIT_EXCEEDED", operation, `Metric "${entry.definition.name}" exceeds the ${maximumAttributeCardinality}-value lifetime limit for one label.`, entry.definition.name, false, undefined, attribute.key);
+            }
+        }
         if (!entry.lifetimeSeries.has(attributes.identity) &&
             entry.lifetimeSeries.size >= maximumInstrumentSeries) {
             throw metricError("LIMIT_EXCEEDED", operation, `Metric "${entry.definition.name}" exceeds the ${maximumInstrumentSeries}-series lifetime limit.`, entry.definition.name, false);
@@ -519,9 +677,18 @@ class MetricsRuntimeState {
         }
         return runtimeIdentity;
     }
-    commitSeries(entry, identity) {
-        entry.lifetimeSeries.add(identity);
-        this.runtimeLifetimeSeries.add(`${entry.definition.name}:${identity}`);
+    commitSeries(entry, attributes) {
+        entry.lifetimeSeries.add(attributes.identity);
+        this.runtimeLifetimeSeries.add(`${entry.definition.name}:${attributes.identity}`);
+        for (const attribute of attributes.values) {
+            const key = `${entry.definition.name}:${attribute.key}`;
+            let values = this.lifetimeValuesByInstrumentKey.get(key);
+            if (values === undefined) {
+                values = new Set();
+                this.lifetimeValuesByInstrumentKey.set(key, values);
+            }
+            values.add(metricScalarIdentity(attribute.value));
+        }
     }
     transportForExport() {
         let selected;
@@ -574,10 +741,10 @@ class MetricsRuntimeState {
         const timeUnixNano = nanosNow();
         const metrics = [];
         const names = new Map();
+        const gaugeFailures = [];
         for (const snapshot of Metric.snapshotUnsafe(this.directContext)) {
-            this.appendDirectMetric(metrics, names, snapshot, timeUnixNano);
+            this.appendDirectMetric(metrics, names, snapshot, timeUnixNano, gaugeFailures);
         }
-        const gaugeFailures = [];
         for (const entry of this.catalog.values()) {
             const existing = names.get(entry.definition.name);
             const definitionIdentity = `${entry.kind}:${entry.definition.unit}:${entry.definition.description}`;
@@ -604,19 +771,15 @@ class MetricsRuntimeState {
                 resourceMetrics: [
                     {
                         resource: {
-                            attributes: [
-                                { key: "service.name", value: { stringValue: this.options.serviceName } },
-                                { key: "service.version", value: { stringValue: this.options.serviceVersion } },
-                                {
-                                    key: "deployment.environment.name",
-                                    value: { stringValue: this.options.environment },
-                                },
-                            ],
+                            attributes: Array.from(this.options.resourceAttributes, ([key, value]) => ({
+                                key,
+                                value: { stringValue: value },
+                            })),
                             droppedAttributesCount: 0,
                         },
                         scopeMetrics: [
                             {
-                                scope: { name: this.options.serviceName },
+                                scope: { name: this.options.identity.serviceName },
                                 metrics,
                             },
                         ],
@@ -626,7 +789,7 @@ class MetricsRuntimeState {
             result: { gaugeFailures },
         };
     }
-    appendDirectMetric(metrics, names, snapshot, timeUnixNano) {
+    appendDirectMetric(metrics, names, snapshot, timeUnixNano, failures) {
         const unit = snapshot.attributes?.unit ?? snapshot.attributes?.time_unit ?? "1";
         const description = snapshot.description ?? "";
         const definitionIdentity = `${snapshot.type}:${unit}:${description}`;
@@ -634,7 +797,9 @@ class MetricsRuntimeState {
         if (existing !== undefined && existing.definition !== definitionIdentity) {
             throw metricError("EXPORT_FAILED", "flush", `Direct Effect metric "${snapshot.id}" has incompatible definitions. Rename or align the definitions before retrying.`, snapshot.id, false);
         }
-        const attributes = directAttributesToOtlp(snapshot.attributes);
+        const policyAttributes = directAttributesToOtlp(snapshot.attributes, snapshot.id, this.options.policy);
+        const attributes = policyAttributes.values;
+        failures.push(...policyAttributes.failures);
         const previous = metrics.find((metric) => metric.name === snapshot.id);
         names.set(snapshot.id, { kind: snapshot.type, definition: definitionIdentity });
         if (snapshot.type === "Counter") {
@@ -896,18 +1061,29 @@ class MetricsRuntimeState {
     collectGauge(entry, timeUnixNano) {
         const observations = [];
         const failures = [];
+        const contractTransaction = new MetricContractTransaction();
         const proposedIdentities = new Set();
         for (const registration of entry.callbacks.values()) {
             let callbackResult;
             try {
                 callbackResult = registration.callback();
             }
-            catch {
-                failures.push({
-                    instrumentName: entry.definition.name,
-                    code: "CALLBACK_FAILED",
-                    message: `Observable gauge "${entry.definition.name}" callback failed and was omitted from this export.`,
-                });
+            catch (cause) {
+                if (cause instanceof InvalidMetricMeasurement) {
+                    failures.push({
+                        instrumentName: entry.definition.name,
+                        code: "CONTRACT_REJECTED",
+                        message: `Observable gauge "${entry.definition.name}" callback violated its metric contract and was omitted from this export.`,
+                        contractReason: cause.code,
+                    });
+                }
+                else {
+                    failures.push({
+                        instrumentName: entry.definition.name,
+                        code: "CALLBACK_FAILED",
+                        message: `Observable gauge "${entry.definition.name}" callback failed and was omitted from this export.`,
+                    });
+                }
                 continue;
             }
             let callbackObservations;
@@ -933,7 +1109,7 @@ class MetricsRuntimeState {
             const callbackBatch = [];
             const callbackIdentities = new Set();
             let callbackFailed = false;
-            for (const observation of callbackObservations) {
+            for (const [index, observation] of callbackObservations.entries()) {
                 if (!Number.isFinite(observation.value)) {
                     failures.push({
                         instrumentName: entry.definition.name,
@@ -944,7 +1120,7 @@ class MetricsRuntimeState {
                     break;
                 }
                 try {
-                    const attributes = parseAttributes(observation.attributes, "collectObservableGauge", entry.definition.name);
+                    const attributes = parseAttributes(observation.attributes, "collectObservableGauge", entry.definition.name, this.policy);
                     if (proposedIdentities.has(attributes.identity) ||
                         callbackIdentities.has(attributes.identity)) {
                         failures.push({
@@ -956,17 +1132,29 @@ class MetricsRuntimeState {
                         break;
                     }
                     callbackIdentities.add(attributes.identity);
+                    const contract = gaugeObservationContracts.get(callbackResult[index] ?? observation);
+                    if (contract !== undefined)
+                        contractTransaction.prepare(contract);
                     callbackBatch.push({ value: observation.value, attributes });
                 }
                 catch (cause) {
-                    const code = cause instanceof MetricsError && cause.code === "LIMIT_EXCEEDED"
-                        ? "ATTRIBUTE_LIMIT_EXCEEDED"
-                        : "INVALID_OBSERVATION";
-                    failures.push({
-                        instrumentName: entry.definition.name,
-                        code,
-                        message: `Observable gauge "${entry.definition.name}" produced invalid bounded attributes.`,
-                    });
+                    if (cause instanceof InvalidMetricMeasurement) {
+                        failures.push({
+                            instrumentName: entry.definition.name,
+                            code: "CONTRACT_REJECTED",
+                            message: `Observable gauge "${entry.definition.name}" callback violated its metric contract and was omitted from this export.`,
+                            contractReason: cause.code,
+                        });
+                    }
+                    else {
+                        failures.push({
+                            instrumentName: entry.definition.name,
+                            code: cause instanceof MetricsError && cause.code === "LIMIT_EXCEEDED"
+                                ? "ATTRIBUTE_LIMIT_EXCEEDED"
+                                : "INVALID_OBSERVATION",
+                            message: `Observable gauge "${entry.definition.name}" produced invalid bounded attributes.`,
+                        });
+                    }
                     callbackFailed = true;
                     break;
                 }
@@ -997,8 +1185,12 @@ class MetricsRuntimeState {
             };
         }
         for (const identity of newIdentities) {
-            this.commitSeries(entry, identity);
+            const observation = observations.find((candidate) => candidate.attributes.identity === identity);
+            if (observation !== undefined) {
+                this.commitSeries(entry, observation.attributes);
+            }
         }
+        contractTransaction.commit();
         return {
             metric: {
                 name: entry.definition.name,
@@ -1126,6 +1318,19 @@ class ActiveMetrics {
         this.lease = lease;
         this.timeoutMilliseconds = timeoutMilliseconds;
     }
+    reserveCounterBatch(measurements) {
+        this.assertOpen("counter");
+        const normalized = measurements.map((measurement) => {
+            const definition = parseDefinition(measurement.definition, "counter");
+            this.assertOpen("add", definition.name);
+            return {
+                definition,
+                value: measurement.value,
+                attributes: parseAttributes(measurement.attributes, "add", definition.name, this.lease.state.policy),
+            };
+        });
+        return this.lease.state.reserveCounterBatch(this.lease.leaseId, normalized);
+    }
     counter(definitionInput) {
         this.assertOpen("counter");
         const definition = parseDefinition(definitionInput, "counter");
@@ -1133,7 +1338,7 @@ class ActiveMetrics {
         return {
             add: (value, attributes) => {
                 this.assertOpen("add", definition.name);
-                const parsedAttributes = parseAttributes(attributes, "add", definition.name);
+                const parsedAttributes = parseAttributes(attributes, "add", definition.name, this.lease.state.policy);
                 this.lease.state.addCounter(this.lease.leaseId, entry, value, parsedAttributes);
             },
         };
@@ -1145,7 +1350,7 @@ class ActiveMetrics {
         return {
             record: (value, attributes) => {
                 this.assertOpen("record", definition.name);
-                const parsedAttributes = parseAttributes(attributes, "record", definition.name);
+                const parsedAttributes = parseAttributes(attributes, "record", definition.name, this.lease.state.policy);
                 this.lease.state.recordHistogram(this.lease.leaseId, entry, value, parsedAttributes);
             },
         };
@@ -1179,6 +1384,13 @@ class ActiveMetrics {
         this.closePromise = this.lease.state.closeLease(this.lease.leaseId, this.timeoutMilliseconds);
         return this.closePromise;
     }
+    releaseWithoutFlush() {
+        if (this.closePromise !== undefined)
+            return this.closePromise;
+        this.closed = true;
+        this.closePromise = this.lease.state.closeLease(this.lease.leaseId, this.timeoutMilliseconds, false);
+        return this.closePromise;
+    }
     assertOpen(operation, instrumentName) {
         if (this.closed) {
             throw metricError("CLOSED", operation, "Metrics lifecycle is closed. Create a new lifecycle before recording or flushing metrics.", instrumentName, false);
@@ -1186,8 +1398,24 @@ class ActiveMetrics {
     }
 }
 class DisabledMetrics {
+    policy;
     closed = false;
     closePromise;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    reserveCounterBatch(measurements) {
+        for (const measurement of measurements) {
+            this.assertOpen("counter");
+            const definition = parseDefinition(measurement.definition, "counter");
+            this.assertOpen("add", definition.name);
+            if (!Number.isFinite(measurement.value) || measurement.value < 0) {
+                throw metricError("INVALID_MEASUREMENT", "add", `Counter "${definition.name}" accepts only finite values greater than or equal to zero.`, definition.name, false);
+            }
+            parseAttributes(measurement.attributes, "add", definition.name, this.policy);
+        }
+        return () => undefined;
+    }
     counter(definitionInput) {
         this.assertOpen("counter");
         const definition = parseDefinition(definitionInput, "counter");
@@ -1197,7 +1425,7 @@ class DisabledMetrics {
                 if (!Number.isFinite(value) || value < 0) {
                     throw metricError("INVALID_MEASUREMENT", "add", `Counter "${definition.name}" accepts only finite values greater than or equal to zero.`, definition.name, false);
                 }
-                parseAttributes(attributes, "add", definition.name);
+                parseAttributes(attributes, "add", definition.name, this.policy);
             },
         };
     }
@@ -1210,7 +1438,7 @@ class DisabledMetrics {
                 if (!Number.isFinite(value)) {
                     throw metricError("INVALID_MEASUREMENT", "record", `Histogram "${definition.name}" accepts only finite values.`, definition.name, false);
                 }
-                parseAttributes(attributes, "record", definition.name);
+                parseAttributes(attributes, "record", definition.name, this.policy);
             },
         };
     }
@@ -1241,17 +1469,128 @@ class DisabledMetrics {
         }
     }
 }
+const metricContractStates = new WeakMap();
+class MetricContractTransaction {
+    valuesByLedger = new Map();
+    prepare(contract) {
+        const state = metricContractStates.get(contract.metrics);
+        if (state === undefined) {
+            throw unsupportedMetricsFacade(contract.metricAlias, contract.metricName);
+        }
+        let stagedByDefinition = this.valuesByLedger.get(state.values);
+        if (stagedByDefinition === undefined) {
+            stagedByDefinition = new Map();
+            this.valuesByLedger.set(state.values, stagedByDefinition);
+        }
+        let stagedValues = stagedByDefinition.get(contract.definitionIdentity);
+        if (stagedValues === undefined) {
+            stagedValues = new Map();
+            stagedByDefinition.set(contract.definitionIdentity, stagedValues);
+        }
+        prepareContractValues(stagedValues, state.values.get(contract.definitionIdentity), contract.metricAlias, contract.metricName, contract.attributes, contract.limits);
+    }
+    commit() {
+        for (const [ledger, stagedByDefinition] of this.valuesByLedger) {
+            for (const [definitionIdentity, stagedValues] of stagedByDefinition) {
+                let committedByAttribute = ledger.get(definitionIdentity);
+                if (committedByAttribute === undefined) {
+                    committedByAttribute = new Map();
+                    ledger.set(definitionIdentity, committedByAttribute);
+                }
+                for (const [attributeName, values] of stagedValues) {
+                    let committedValues = committedByAttribute.get(attributeName);
+                    if (committedValues === undefined) {
+                        committedValues = new Set();
+                        committedByAttribute.set(attributeName, committedValues);
+                    }
+                    for (const identity of values)
+                        committedValues.add(identity);
+                }
+            }
+        }
+    }
+}
+const unsupportedMetricsFacade = (metricAlias, metricName) => new InvalidMetricMeasurement({
+    code: "OBS_METRIC_INVALID_VALUE",
+    operation: "record",
+    message: `Metric alias "${metricAlias}" is bound to an unsupported metrics facade. Use createMetrics or a Node observability handle.`,
+    metricAlias,
+    metricName,
+});
+export const reserveMetricCounterBatch = (metrics, measurements) => {
+    const contractTransaction = new MetricContractTransaction();
+    for (const measurement of measurements)
+        contractTransaction.prepare(measurement.admission);
+    if (metrics instanceof ActiveMetrics || metrics instanceof DisabledMetrics) {
+        const commit = metrics.reserveCounterBatch(measurements);
+        contractTransaction.commit();
+        return commit;
+    }
+    const measurement = measurements[0];
+    throw unsupportedMetricsFacade(measurement?.definition.name ?? "counter", measurement?.definition.name ?? "counter");
+};
+const prepareContractValues = (stagedValues, committedValues, metricAlias, metricName, attributes, limits) => {
+    for (const limit of limits) {
+        const attribute = attributes.find((candidate) => candidate.key === limit.attributeName);
+        if (attribute === undefined)
+            continue;
+        let values = stagedValues.get(limit.attributeName);
+        if (values === undefined) {
+            values = new Set(committedValues?.get(limit.attributeName));
+            stagedValues.set(limit.attributeName, values);
+        }
+        const identity = metricScalarIdentity(attribute.value);
+        if (!values.has(identity) && values.size >= limit.maximumCardinality) {
+            throw new InvalidMetricMeasurement({
+                code: "OBS_METRIC_CARDINALITY_EXCEEDED",
+                operation: "record",
+                message: `Metric "${metricName}" attribute "${limit.attributeName}" exceeds its declared maximum cardinality of ${limit.maximumCardinality}. Reuse a declared value or revise the contract.`,
+                metricAlias,
+                metricName,
+                attributeName: limit.attributeName,
+            });
+        }
+        values.add(identity);
+    }
+};
+export const prepareContractMetricBatch = (admissions) => {
+    const transaction = new MetricContractTransaction();
+    for (const admission of admissions)
+        transaction.prepare(admission);
+    return () => transaction.commit();
+};
+export const prepareContractMetricAttributes = (metrics, metricAlias, metricName, definitionIdentity, attributes, limits) => prepareContractMetricBatch([
+    { metrics, metricAlias, metricName, definitionIdentity, attributes, limits },
+]);
+export const releaseMetricsLease = async (metrics) => {
+    if (metrics instanceof ActiveMetrics) {
+        await metrics.releaseWithoutFlush();
+        return;
+    }
+    await metrics.close();
+};
+export const createDisabledMetrics = (policy = baseDataPolicy) => {
+    const metrics = new DisabledMetrics(policy);
+    metricContractStates.set(metrics, { values: new WeakMap() });
+    return metrics;
+};
 export const createStandaloneMetrics = async (optionsInput) => {
     const options = parseOptions(optionsInput);
     if (!options.enabled) {
-        return new DisabledMetrics();
+        return createDisabledMetrics(options.policy);
     }
     const lease = acquireRuntime(options, {
         kind: "fetch",
         send: fetchTransport(options.metricsEndpoint),
     });
-    return new ActiveMetrics(lease, options.flushTimeoutMilliseconds);
+    const metrics = new ActiveMetrics(lease, options.flushTimeoutMilliseconds);
+    metricContractStates.set(metrics, {
+        values: lease.state.contractValuesByDefinition,
+    });
+    return metrics;
 };
+export class LayerMetricsRuntime extends Context.Service()("@equipe-tech/observability/internal/LayerMetricsRuntime") {
+}
 const makeEffectTransport = (endpoint, client) => {
     const request = HttpClientRequest.post(endpoint, {
         headers: { "content-type": "application/json" },
@@ -1269,18 +1608,37 @@ const makeMetricsRuntime = Effect.fn("makeMetricsRuntime")(function* (config, op
     const client = yield* HttpClient.HttpClient;
     const flusher = yield* OtlpExporter.Flusher;
     const parsed = parseOptions({
-        serviceName: config.serviceName,
-        serviceVersion: config.serviceVersion,
-        environment: config.environment,
+        serviceName: config.identity.serviceName,
+        serviceVersion: config.identity.serviceVersion,
+        environment: config.identity.environment,
+        deploymentEnvironmentAlias: config.environmentAlias,
         otlpEndpoint: config.otlpEndpoint.toString(),
         flushTimeoutMilliseconds: options.shutdownTimeoutMilliseconds,
+        policy: options.policy,
     });
-    const lease = acquireRuntime(parsed, {
+    const resourceAttributes = new Map(options.resourceAttributes);
+    resourceAttributes.delete("service.instance.id");
+    const parsedResourceKey = JSON.stringify(Array.from(parsed.resourceAttributes));
+    const resourceKey = JSON.stringify(Array.from(resourceAttributes));
+    const normalized = {
+        ...parsed,
+        poolKey: resourceKey === parsedResourceKey
+            ? parsed.poolKey
+            : JSON.stringify([parsed.poolKey, resourceKey]),
+        resourceAttributes,
+    };
+    const transport = {
         kind: "layer",
-        send: makeEffectTransport(parsed.metricsEndpoint, client),
-    });
+        send: makeEffectTransport(normalized.metricsEndpoint, client),
+    };
+    const lease = acquireRuntime(normalized, transport);
     yield* flusher.register(Effect.tryPromise(() => lease.state.flush(parsed.flushTimeoutMilliseconds)).pipe(Effect.catch(() => Effect.void), Effect.asVoid));
     yield* Effect.addFinalizer(() => Effect.tryPromise(() => lease.state.closeLease(lease.leaseId, parsed.flushTimeoutMilliseconds)).pipe(Effect.catch(() => Effect.void), Effect.asVoid));
-    return lease.state.registry;
+    const acquireMetrics = () => {
+        const metrics = new ActiveMetrics(lease.state.acquire(transport), parsed.flushTimeoutMilliseconds);
+        metricContractStates.set(metrics, { values: lease.state.contractValuesByDefinition });
+        return metrics;
+    };
+    return Context.make(Metric.MetricRegistry, lease.state.registry).pipe(Context.add(LayerMetricsRuntime, LayerMetricsRuntime.of({ acquireMetrics })));
 });
-export const layerMetricsRuntime = (config, options) => Layer.effect(Metric.MetricRegistry, makeMetricsRuntime(config, options)).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));
+export const layerMetricsRuntime = (config, options) => Layer.effectContext(makeMetricsRuntime(config, options)).pipe(Layer.provideMerge(OtlpExporter.layerFlusher));