@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/monitoring/observability/audit-observation-emission.backend.js

@@ -0,0 +1,385 @@
+/**
+ * # The seam every FIRE-AND-FORGET audit observation goes through — and the loss signal behind it
+ *
+ * assurance-control: WILDO.AUDIT.SECURITY_EVENT — a lost security observation is DETECTABLE, so a
+ * period with no recorded operator crossings is distinguishable from a period with a broken sink.
+ *
+ * ## The gap this closes, stated precisely
+ *
+ * A handful of security observations — an operator crossing a tenant boundary, an authorization
+ * refusal, a platform-access grant transition, a directory read — are emitted WITHOUT `await`, with
+ * the audit service FEATURE-DETECTED and the returned promise's rejection SWALLOWED. Every one of
+ * those three properties is deliberate and must survive: **an observation must never be able to fail
+ * the request it observes.** A fail-closed variant would hand anyone a way to disable operator
+ * support, or to convert a correct 403 into a 500, by breaking the audit sink.
+ *
+ * What was missing is not a refusal — it is a COUNT. With nothing recording the drops, an operator
+ * reading the trail cannot tell "no operator crossed a tenant boundary this week" from "the audit
+ * service has been unbound since Tuesday". Those two readings of the same empty result are what make
+ * the evidence worthless, and it is the same shape as
+ * `.claude/rules/negative-results-require-a-positive-probe.md`: an empty result is evidence about the
+ * pipeline, never about the world.
+ *
+ * ## What the existing control does NOT cover — measured 2026-09-09
+ *
+ * Three call sites carried the claim that *"detection of a lost row is the audit pipeline's own
+ * control (`audit_store_failure_total`), not this gate's"*. That claim is **true for one loss shape
+ * and false for the three that matter here.** `AuditLogsBackendService._createAuditLog` catches its
+ * Layer-1 store write and increments `audit_store_failure_total` — so a store that is DOWN while the
+ * service is bound and reachable is already counted. But that counter is inside a method the
+ * observer may never reach:
+ *
+ * | Loss shape | Reaches `_createAuditLog`? | Counted before this seam |
+ * |---|---|---|
+ * | {@link AuditObservationLossReason.SERVICE_UNAVAILABLE} — the audit service is unbound, or the `log*` method is absent (a partial DI binding, a host binding an older audit service) | no | **nothing at all** |
+ * | {@link AuditObservationLossReason.EMISSION_THREW} — the call threw synchronously | no | **nothing at all** |
+ * | {@link AuditObservationLossReason.EMISSION_REJECTED} — the returned promise rejected | partially | **nothing at all** at the observer |
+ * | the Layer-1 store write itself failed | yes | `audit_store_failure_total` (unchanged, and still the right control for that shape) |
+ *
+ * So this seam counts the OBSERVER-side drop — the case where the audit pipeline never learned there
+ * was anything to record — and leaves the pipeline's own control alone. The two are complementary,
+ * not duplicates, and a reviewer needs both: one says "we tried and the store refused", the other
+ * says "we never got as far as trying".
+ *
+ * ## Why a METRIC and a LOG, and not an audit row
+ *
+ * The loss signal must survive the audit store being down, so it cannot BE the audit store —
+ * recording "the audit store was unreachable" in the audit store is the circularity that makes the
+ * whole thing worthless. Two channels, deliberately, because neither alone is sufficient:
+ *
+ * - **`audit_observation_dropped_total`** (via {@link MetricsService.recordAuditObservationDropped})
+ *   is the RATE signal, and it is the durable one: the OTLP reader exports it periodically to the
+ *   metrics backend, so its value outlives the process and aggregates across instances. Without the
+ *   OTLP preload wired the global meter is a no-op and this channel is silently inert — which is
+ *   precisely why it is not the only channel.
+ * - **One rate-limited `error` log line** is the always-available channel and the WAKE-UP. It fires
+ *   at most once per {@link LOSS_LOG_INTERVAL_MS} per `(observation, reason)` pair, so a service
+ *   that has been unbound since boot produces one line rather than one per request. Unthrottled it
+ *   would flood, and a channel that floods is a channel operators filter out — which would leave the
+ *   signal technically present and practically absent.
+ *
+ * ## The process-local accumulator, argued rather than assumed
+ *
+ * {@link readAuditObservationLossTotals} is per-process and is **lost on restart**. That is stated
+ * here rather than glossed, because a reader could otherwise take it for durable evidence:
+ *
+ * - It is **not** the evidence. It is a test seam and a door for a future health surface. The
+ *   durable record is the exported counter (metrics backend) plus the log line (log store).
+ * - Per-instance is the correct granularity for the LOG channel anyway — "which replica lost
+ *   evidence" is part of the answer — and the metrics backend does the cross-instance aggregation
+ *   that a process-local number never could.
+ * - Rejected: a durable row for each loss. It is I/O on the observation path, it can fail the
+ *   request the whole design forbids failing, and it introduces a second store that can itself be
+ *   down. Rejected: a dedicated health endpoint. Still per-instance, adds a surface, and gives an
+ *   operator nothing the counter does not already give them.
+ *
+ * ## Why this is a SEAM and not a helper each site copies
+ *
+ * `.claude/rules/invariant-call-site-enumeration.md` — the invariant here ("a dropped observation is
+ * counted") holds at every fire-and-forget security observation in the package, spread across six
+ * subtrees, and the recurring defect in this repository is exactly the invariant applied at one of
+ * them. Routing every site through one function makes the counting structural rather than
+ * remembered: a new fire-and-forget observation that uses this seam is counted the day it lands,
+ * with no author having to know this mechanism exists.
+ *
+ * **Do not quote a call-site count from this file.** An earlier revision named one ("EIGHT call
+ * sites"), and the very next adoption pass made it wrong — a number in prose is one a reader has to
+ * re-measure before believing, which is worse than no number. Measure it:
+ *
+ * ```bash
+ * command grep -rn "emitAuditObservation(\|recordAuditObservationLoss(" engine/saas-backend-lib/src \
+ *   | grep -v __tests__ | grep -v audit-observation-emission.backend.ts
+ * ```
+ */
+/**
+ * WHICH security observation was lost.
+ *
+ * A closed vocabulary with one named runtime source, per `CLAUDE.md` — the member is what a reviewer
+ * reads off the alert, so it has to carry its own explanation rather than being a bare string at
+ * every call site. It is also the metric's `observation` label: bounded, low cardinality, and stable
+ * across renames of the emitting method.
+ *
+ * ## A member names the EVIDENCE, never the emitter
+ *
+ * Two members of this enum are emitted from more than one place, and that is the design rather than
+ * an omission. `CROSS_TENANT_ADMINISTRATIVE_ACCESS` is raised by the per-instance tenant gate AND by
+ * the APPLICATION-scoped collection read; `HTTP_API_READ_THROUGH_ACCESS` by the per-read adapter AND
+ * by the per-run ETL pipeline. Splitting either by emitter would make the one question an operator
+ * actually asks — *how much cross-tenant evidence did we lose?* — a sum over labels, and a sum
+ * somebody has to remember to widen is a sum that goes quietly wrong the day a third emitter lands.
+ * WHICH door dropped it is carried by the log line's `context`, which is the channel with room for
+ * it; the metric carries the rate, which is the thing that has to aggregate.
+ *
+ * The corollary: when you add an emitter for an event a member already names, REUSE the member and
+ * extend its JSDoc to name the new emitter. A member whose prose still names one of two emitters is
+ * a stale claim in the place a reviewer trusts most.
+ */
+export var AuditObservationKind;
+(function (AuditObservationKind) {
+    /**
+     * `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, from BOTH doors that can produce one.
+     *
+     * The most consequential member: this is the operator-crossing trail
+     * `.claude/rules/administrative-continuity-floors.md` requires, and the one whose silence is
+     * indistinguishable from "no operator crossed anything".
+     *
+     * - `authorizeOrganizations` — the per-instance tenant gate, deciding on ONE fetched row.
+     * - `ServiceResourceBackendService.recordCrossTenantReadAccess` — the APPLICATION-scoped
+     *   collection read, one observation per TENANT reached. The authorizer never sees this half: it
+     *   runs only for ORGANIZATIONS-scoped resources, and an application-scoped door returns a SET
+     *   whose rows belong to many tenants. Losing it silently is the larger of the two exposures,
+     *   because it is the door that can enumerate every tenant at once.
+     */
+    AuditObservationKind["CROSS_TENANT_ADMINISTRATIVE_ACCESS"] = "cross_tenant_administrative_access";
+    /**
+     * `RESOURCE_OPERATION_DENIED` from the authorizer funnel. A lost refusal is a lost negative access
+     * decision — the record half of "record access decisions".
+     */
+    AuditObservationKind["AUTHORIZATION_DENIAL"] = "authorization_denial";
+    /**
+     * `PLATFORM_ACCESS_GRANT_LIFECYCLE` from the grant custom implementation. A lost transition means
+     * an elevation exists whose request/approval is not in the trail.
+     */
+    AuditObservationKind["PLATFORM_ACCESS_GRANT_LIFECYCLE"] = "platform_access_grant_lifecycle";
+    /**
+     * `PLATFORM_DIRECTORY_ACCESS` from `ServiceResourceBackendService.recordPlatformDirectoryAccess` —
+     * an APPLICATION-WIDE directory enumeration that no scope confined.
+     *
+     * `returnedCount` is why the row exists at all: it is the only thing separating "an operator
+     * opened the directory" from "an operator exported it". A lost observation does not merely lose an
+     * access record, it loses the SIZE, which is the half a reviewer reads first.
+     */
+    AuditObservationKind["PLATFORM_DIRECTORY_ACCESS"] = "platform_directory_access";
+    /**
+     * `USER_SESSION_EVICTED` from the token issuer's concurrent-session cap.
+     *
+     * One observation per RETIRED refresh chain, not per enforcement: the cap bounds the blast radius
+     * of undetected token theft, so a burst of evictions for one principal is among the more
+     * interesting things the trail can carry — and a burst is exactly the case where losing some of
+     * the rows understates it. Counting per chain is what keeps the loss signal proportional to the
+     * evidence actually lost rather than to the number of times the cap ran.
+     */
+    AuditObservationKind["USER_SESSION_EVICTED"] = "user_session_evicted";
+    /**
+     * `PROVIDER_OPERATION_CALL` from the provider operation executor — one row per OUTBOUND call to a
+     * third party, on both the success and the failure path.
+     *
+     * This is the application's record of what it sent to whom on whose behalf. Its silence is
+     * peculiarly misleading: an empty outbound trail reads as "this deployment integrates with
+     * nothing", which is a sentence somebody will believe.
+     */
+    AuditObservationKind["PROVIDER_OPERATION_CALL"] = "provider_operation_call";
+    /**
+     * The post-call credential-use stamp from the provider operation executor.
+     *
+     * ## Why this is on THIS counter even though its sink is not the audit service
+     *
+     * It writes to the tenant's own credential row rather than to `AuditLogsBackendService`, and it is
+     * still the identical observer-side loss shape: fire-and-forget, sink feature-detected, rejection
+     * swallowed, nothing counting the drops. The counter's subject is the LOSS OF A SECURITY
+     * OBSERVATION, not the identity of the store that was supposed to receive it — so a second counter
+     * for one site would fragment the alert without telling an operator anything the `observation`
+     * label does not already say.
+     *
+     * What it evidences is narrow and worth stating: whether a stored credential was ACCEPTED by the
+     * provider on last use. Losing it leaves a credential whose health is unknown, which surfaces
+     * later as an integration that fails with no record of when it started failing.
+     */
+    AuditObservationKind["PROVIDER_CREDENTIAL_USE"] = "provider_credential_use";
+    /**
+     * `HTTP_API_READ_THROUGH_ACCESS`, from BOTH emitters — see the enum's naming principle above.
+     *
+     * - `HttpApiResourceRepositoryBackendService.recordReadThroughAccess` — one observation per remote
+     *   round-trip, and the only tier that witnesses every one of them (repository-direct probes never
+     *   reach the services tier at all).
+     * - `ExternalDataPipelineRunBackendService.recordRunReadThroughAccess` — one observation per ETL
+     *   run.
+     *
+     * The evidence at stake is ATTRIBUTION: an HTTP_API read reaches a third party through a SHARED
+     * service principal, so this row is what carries the real initiating user through it. Without it
+     * the external system's own logs show one principal and nothing anywhere resolves it to a person.
+     */
+    AuditObservationKind["HTTP_API_READ_THROUGH_ACCESS"] = "http_api_read_through_access";
+})(AuditObservationKind || (AuditObservationKind = {}));
+/**
+ * WHY the observation never reached the audit pipeline.
+ *
+ * Three members, and they are genuinely different diagnoses rather than shades of one — see the
+ * table in this module's header. `SERVICE_UNAVAILABLE` is a WIRING fault and is usually total and
+ * permanent for the life of the process; the other two are runtime faults and are usually partial.
+ * Merging them would leave an operator unable to tell "this deployment audits nothing" from "the
+ * audit store hiccupped twice".
+ */
+export var AuditObservationLossReason;
+(function (AuditObservationLossReason) {
+    /** The audit service is unbound, or the specific `log*` method is absent on the bound instance. */
+    AuditObservationLossReason["SERVICE_UNAVAILABLE"] = "service_unavailable";
+    /** The emitting call threw synchronously — before any `.catch()` could make it fire-and-forget. */
+    AuditObservationLossReason["EMISSION_THREW"] = "emission_threw";
+    /** The emitting call returned a promise that rejected. */
+    AuditObservationLossReason["EMISSION_REJECTED"] = "emission_rejected";
+})(AuditObservationLossReason || (AuditObservationLossReason = {}));
+/**
+ * How often ONE `(observation, reason)` pair may produce a log line.
+ *
+ * Fifteen minutes: long enough that a permanently broken binding costs four lines an hour rather
+ * than one per request, short enough that a NEW outage hours after an earlier one still announces
+ * itself instead of being swallowed by a latch that never resets. A permanent latch was rejected for
+ * exactly that reason — it makes the second incident invisible.
+ */
+export const LOSS_LOG_INTERVAL_MS = 15 * 60 * 1000;
+/** Process-local totals, keyed `<observation>:<reason>`. Not evidence — see the module header. */
+const lossTotals = new Map();
+/** Last log timestamp per `<observation>:<reason>`. Bounded by the enum cross-product (9 entries). */
+const lastLoggedAt = new Map();
+/**
+ * Every loss recorded since this process started, as `<observation>:<reason>` → count.
+ *
+ * A COPY, so a caller cannot mutate the accumulator. Exists so the counting can be pinned without an
+ * OTLP backend, and so a future health surface has a door that does not require one either. Read the
+ * module header before treating the numbers as durable evidence: they are not.
+ */
+export function readAuditObservationLossTotals() {
+    return Object.fromEntries(lossTotals);
+}
+/** Test isolation only. Never called from production code. */
+export function resetAuditObservationLossTotals() {
+    lossTotals.clear();
+    lastLoggedAt.clear();
+}
+/**
+ * Record one lost observation. Never throws, under any circumstance.
+ *
+ * Exported so a site whose emission does not fit {@link emitAuditObservation}'s shape can still
+ * contribute to the same counter rather than inventing a second one. Prefer the seam.
+ */
+export function recordAuditObservationLoss(params) {
+    // The recorder is the LAST thing that may fail the request it observes: a metric backend that
+    // throws, or a logger that throws, would defeat the entire purpose of the fire-and-forget contract
+    // this seam exists to preserve. Everything below is inside one boundary for that reason.
+    try {
+        const key = `${params.observation}:${params.reason}`;
+        lossTotals.set(key, (lossTotals.get(key) ?? 0) + 1);
+        // Metrics FIRST. It is the durable, rate-carrying channel, and it must be incremented even for
+        // the drops the throttle below decides not to log — otherwise the throttle would silently
+        // suppress the count as well as the line, which is the defect one layer up.
+        //
+        // Feature-DETECTED rather than optional-chained on the object, and for the reason this whole
+        // module exists: a container that answers every symbol with a stub (the shape several partial
+        // test containers in this package genuinely have) yields a truthy `metricsService` whose method
+        // is absent, so `?.` on the OBJECT still calls `undefined(...)` and throws. The outer catch
+        // would contain it, but a swallowed TypeError looks exactly like a swallowed real defect — and
+        // it would take the log line down with it, leaving the loss silent again.
+        const metricsService = params.metricsService ?? resolveLossMetricsRecorder(params.metricsResolver);
+        if (typeof metricsService?.recordAuditObservationDropped === 'function') {
+            metricsService.recordAuditObservationDropped({
+                observation: params.observation,
+                reason: params.reason,
+            });
+        }
+        const now = Date.now();
+        const previous = lastLoggedAt.get(key);
+        if (previous !== undefined && now - previous < LOSS_LOG_INTERVAL_MS)
+            return;
+        lastLoggedAt.set(key, now);
+        params.logger?.error?.('A security audit observation was DROPPED before it reached the audit pipeline', {
+            // `reason` is the slug an alert rule and a log query both key on; keep it first and stable.
+            reason: 'audit_observation_dropped',
+            observation: params.observation,
+            lossReason: params.reason,
+            // The running total makes ONE throttled line carry the volume the suppressed lines would have.
+            occurrencesSinceProcessStart: lossTotals.get(key),
+            logIntervalMs: LOSS_LOG_INTERVAL_MS,
+            ...(params.error === undefined ? {} : { error: describeLossError(params.error) }),
+            ...(params.context ?? {}),
+        });
+    }
+    catch {
+        /* An observability failure must never be able to fail the request it observes. */
+    }
+}
+/**
+ * Emit one fire-and-forget audit observation, counting it if it is lost.
+ *
+ * ## The contract, which is the whole point
+ *
+ * **This function never throws and never returns a promise.** Not on an absent service, not on a
+ * synchronous throw, not on a rejection, and not on a metrics or logger failure. Callers rely on it
+ * to preserve the property their own JSDoc promises: the observation cannot fail the request.
+ *
+ * @param params.emit The emitting call, or `undefined` when the audit service or its method is
+ *   absent. Passing `undefined` is how a site reports {@link AuditObservationLossReason.SERVICE_UNAVAILABLE}
+ *   — the feature detection stays at the site because the method name differs per observation, and a
+ *   generic reflective lookup here would trade a compile-time error for a runtime one.
+ */
+export function emitAuditObservation(params) {
+    const loss = (reason, error) => recordAuditObservationLoss({
+        observation: params.observation,
+        reason,
+        metricsService: params.metricsService,
+        metricsResolver: params.metricsResolver,
+        logger: params.logger,
+        error,
+        context: params.context,
+    });
+    try {
+        if (!params.emit) {
+            loss(AuditObservationLossReason.SERVICE_UNAVAILABLE);
+            return;
+        }
+        let result;
+        try {
+            result = params.emit();
+        }
+        catch (error) {
+            // A `log*` method that is absent on a partially-mocked double throws a TypeError HERE —
+            // synchronously, before any `.catch()` could attach. That is the shape the feature detection at
+            // each site exists to pre-empt; this catch is what keeps a site that forgets it from crashing.
+            loss(AuditObservationLossReason.EMISSION_THREW, error);
+            return;
+        }
+        // Optional-chained, because an audit method is free to be synchronous (and every test double
+        // returning `undefined` is). A non-thenable result is a successful emission, not a loss.
+        const thenable = result;
+        if (typeof thenable?.catch !== 'function')
+            return;
+        thenable.catch((error) => loss(AuditObservationLossReason.EMISSION_REJECTED, error));
+    }
+    catch {
+        /* Belt and braces: nothing in this seam may reach the caller. */
+    }
+}
+/**
+ * Ask a site's thunk for the recorder, and treat any refusal as "no recorder".
+ *
+ * Its own `try`, INSIDE the caller's: a container that throws while resolving a binding must not be
+ * able to take the LOG channel down with it. Degrading a loss to its log-only form is the correct
+ * direction — the whole point of this module is that an observability gap is never a reason to
+ * refuse — whereas letting the throw escape to the outer `catch` would silence both channels for the
+ * one event that most needs saying.
+ */
+function resolveLossMetricsRecorder(resolver) {
+    if (typeof resolver !== 'function')
+        return undefined;
+    try {
+        return resolver();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A log-safe description of whatever was thrown.
+ *
+ * Deliberately local rather than routed through `describeCaughtError`: this module sits UNDER the
+ * error subsystem in the dependency order (the error builder's own failures are observations this
+ * seam records), and importing upward would make an observability module depend on the layer it
+ * observes. The shape is a strict subset of what `describeCaughtError` produces, so a log query
+ * reading `error.message` works against both.
+ */
+function describeLossError(error) {
+    if (error instanceof Error)
+        return { message: error.message, name: error.name };
+    return { message: typeof error === 'string' ? error : String(error) };
+}
+//# sourceMappingURL=audit-observation-emission.backend.js.map

package/dist/esm/monitoring/observability/audit-observation-emission.backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-observation-emission.backend.js","sourceRoot":"","sources":["../../../../../src/monitoring/observability/audit-observation-emission.backend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * # The seam every FIRE-AND-FORGET audit observation goes through — and the loss signal behind it\n *\n * assurance-control: WILDO.AUDIT.SECURITY_EVENT — a lost security observation is DETECTABLE, so a\n * period with no recorded operator crossings is distinguishable from a period with a broken sink.\n *\n * ## The gap this closes, stated precisely\n *\n * A handful of security observations — an operator crossing a tenant boundary, an authorization\n * refusal, a platform-access grant transition, a directory read — are emitted WITHOUT `await`, with\n * the audit service FEATURE-DETECTED and the returned promise's rejection SWALLOWED. Every one of\n * those three properties is deliberate and must survive: **an observation must never be able to fail\n * the request it observes.** A fail-closed variant would hand anyone a way to disable operator\n * support, or to convert a correct 403 into a 500, by breaking the audit sink.\n *\n * What was missing is not a refusal — it is a COUNT. With nothing recording the drops, an operator\n * reading the trail cannot tell \"no operator crossed a tenant boundary this week\" from \"the audit\n * service has been unbound since Tuesday\". Those two readings of the same empty result are what make\n * the evidence worthless, and it is the same shape as\n * `.claude/rules/negative-results-require-a-positive-probe.md`: an empty result is evidence about the\n * pipeline, never about the world.\n *\n * ## What the existing control does NOT cover — measured 2026-09-09\n *\n * Three call sites carried the claim that *\"detection of a lost row is the audit pipeline's own\n * control (`audit_store_failure_total`), not this gate's\"*. That claim is **true for one loss shape\n * and false for the three that matter here.** `AuditLogsBackendService._createAuditLog` catches its\n * Layer-1 store write and increments `audit_store_failure_total` — so a store that is DOWN while the\n * service is bound and reachable is already counted. But that counter is inside a method the\n * observer may never reach:\n *\n * | Loss shape | Reaches `_createAuditLog`? | Counted before this seam |\n * |---|---|---|\n * | {@link AuditObservationLossReason.SERVICE_UNAVAILABLE} — the audit service is unbound, or the `log*` method is absent (a partial DI binding, a host binding an older audit service) | no | **nothing at all** |\n * | {@link AuditObservationLossReason.EMISSION_THREW} — the call threw synchronously | no | **nothing at all** |\n * | {@link AuditObservationLossReason.EMISSION_REJECTED} — the returned promise rejected | partially | **nothing at all** at the observer |\n * | the Layer-1 store write itself failed | yes | `audit_store_failure_total` (unchanged, and still the right control for that shape) |\n *\n * So this seam counts the OBSERVER-side drop — the case where the audit pipeline never learned there\n * was anything to record — and leaves the pipeline's own control alone. The two are complementary,\n * not duplicates, and a reviewer needs both: one says \"we tried and the store refused\", the other\n * says \"we never got as far as trying\".\n *\n * ## Why a METRIC and a LOG, and not an audit row\n *\n * The loss signal must survive the audit store being down, so it cannot BE the audit store —\n * recording \"the audit store was unreachable\" in the audit store is the circularity that makes the\n * whole thing worthless. Two channels, deliberately, because neither alone is sufficient:\n *\n * - **`audit_observation_dropped_total`** (via {@link MetricsService.recordAuditObservationDropped})\n *   is the RATE signal, and it is the durable one: the OTLP reader exports it periodically to the\n *   metrics backend, so its value outlives the process and aggregates across instances. Without the\n *   OTLP preload wired the global meter is a no-op and this channel is silently inert — which is\n *   precisely why it is not the only channel.\n * - **One rate-limited `error` log line** is the always-available channel and the WAKE-UP. It fires\n *   at most once per {@link LOSS_LOG_INTERVAL_MS} per `(observation, reason)` pair, so a service\n *   that has been unbound since boot produces one line rather than one per request. Unthrottled it\n *   would flood, and a channel that floods is a channel operators filter out — which would leave the\n *   signal technically present and practically absent.\n *\n * ## The process-local accumulator, argued rather than assumed\n *\n * {@link readAuditObservationLossTotals} is per-process and is **lost on restart**. That is stated\n * here rather than glossed, because a reader could otherwise take it for durable evidence:\n *\n * - It is **not** the evidence. It is a test seam and a door for a future health surface. The\n *   durable record is the exported counter (metrics backend) plus the log line (log store).\n * - Per-instance is the correct granularity for the LOG channel anyway — \"which replica lost\n *   evidence\" is part of the answer — and the metrics backend does the cross-instance aggregation\n *   that a process-local number never could.\n * - Rejected: a durable row for each loss. It is I/O on the observation path, it can fail the\n *   request the whole design forbids failing, and it introduces a second store that can itself be\n *   down. Rejected: a dedicated health endpoint. Still per-instance, adds a surface, and gives an\n *   operator nothing the counter does not already give them.\n *\n * ## Why this is a SEAM and not a helper each site copies\n *\n * `.claude/rules/invariant-call-site-enumeration.md` — the invariant here (\"a dropped observation is\n * counted\") holds at every fire-and-forget security observation in the package, spread across six\n * subtrees, and the recurring defect in this repository is exactly the invariant applied at one of\n * them. Routing every site through one function makes the counting structural rather than\n * remembered: a new fire-and-forget observation that uses this seam is counted the day it lands,\n * with no author having to know this mechanism exists.\n *\n * **Do not quote a call-site count from this file.** An earlier revision named one (\"EIGHT call\n * sites\"), and the very next adoption pass made it wrong — a number in prose is one a reader has to\n * re-measure before believing, which is worse than no number. Measure it:\n *\n * ```bash\n * command grep -rn \"emitAuditObservation(\\|recordAuditObservationLoss(\" engine/saas-backend-lib/src \\\n *   | grep -v __tests__ | grep -v audit-observation-emission.backend.ts\n * ```\n */\n\nimport type { MetricsService } from '~wildo-backend-lib/monitoring/observability/services/metrics.service';\n\n/**\n * WHICH security observation was lost.\n *\n * A closed vocabulary with one named runtime source, per `CLAUDE.md` — the member is what a reviewer\n * reads off the alert, so it has to carry its own explanation rather than being a bare string at\n * every call site. It is also the metric's `observation` label: bounded, low cardinality, and stable\n * across renames of the emitting method.\n *\n * ## A member names the EVIDENCE, never the emitter\n *\n * Two members of this enum are emitted from more than one place, and that is the design rather than\n * an omission. `CROSS_TENANT_ADMINISTRATIVE_ACCESS` is raised by the per-instance tenant gate AND by\n * the APPLICATION-scoped collection read; `HTTP_API_READ_THROUGH_ACCESS` by the per-read adapter AND\n * by the per-run ETL pipeline. Splitting either by emitter would make the one question an operator\n * actually asks — *how much cross-tenant evidence did we lose?* — a sum over labels, and a sum\n * somebody has to remember to widen is a sum that goes quietly wrong the day a third emitter lands.\n * WHICH door dropped it is carried by the log line's `context`, which is the channel with room for\n * it; the metric carries the rate, which is the thing that has to aggregate.\n *\n * The corollary: when you add an emitter for an event a member already names, REUSE the member and\n * extend its JSDoc to name the new emitter. A member whose prose still names one of two emitters is\n * a stale claim in the place a reviewer trusts most.\n */\nexport enum AuditObservationKind {\n  /**\n   * `CROSS_TENANT_ADMINISTRATIVE_ACCESS`, from BOTH doors that can produce one.\n   *\n   * The most consequential member: this is the operator-crossing trail\n   * `.claude/rules/administrative-continuity-floors.md` requires, and the one whose silence is\n   * indistinguishable from \"no operator crossed anything\".\n   *\n   * - `authorizeOrganizations` — the per-instance tenant gate, deciding on ONE fetched row.\n   * - `ServiceResourceBackendService.recordCrossTenantReadAccess` — the APPLICATION-scoped\n   *   collection read, one observation per TENANT reached. The authorizer never sees this half: it\n   *   runs only for ORGANIZATIONS-scoped resources, and an application-scoped door returns a SET\n   *   whose rows belong to many tenants. Losing it silently is the larger of the two exposures,\n   *   because it is the door that can enumerate every tenant at once.\n   */\n  CROSS_TENANT_ADMINISTRATIVE_ACCESS = 'cross_tenant_administrative_access',\n\n  /**\n   * `RESOURCE_OPERATION_DENIED` from the authorizer funnel. A lost refusal is a lost negative access\n   * decision — the record half of \"record access decisions\".\n   */\n  AUTHORIZATION_DENIAL = 'authorization_denial',\n\n  /**\n   * `PLATFORM_ACCESS_GRANT_LIFECYCLE` from the grant custom implementation. A lost transition means\n   * an elevation exists whose request/approval is not in the trail.\n   */\n  PLATFORM_ACCESS_GRANT_LIFECYCLE = 'platform_access_grant_lifecycle',\n\n  /**\n   * `PLATFORM_DIRECTORY_ACCESS` from `ServiceResourceBackendService.recordPlatformDirectoryAccess` —\n   * an APPLICATION-WIDE directory enumeration that no scope confined.\n   *\n   * `returnedCount` is why the row exists at all: it is the only thing separating \"an operator\n   * opened the directory\" from \"an operator exported it\". A lost observation does not merely lose an\n   * access record, it loses the SIZE, which is the half a reviewer reads first.\n   */\n  PLATFORM_DIRECTORY_ACCESS = 'platform_directory_access',\n\n  /**\n   * `USER_SESSION_EVICTED` from the token issuer's concurrent-session cap.\n   *\n   * One observation per RETIRED refresh chain, not per enforcement: the cap bounds the blast radius\n   * of undetected token theft, so a burst of evictions for one principal is among the more\n   * interesting things the trail can carry — and a burst is exactly the case where losing some of\n   * the rows understates it. Counting per chain is what keeps the loss signal proportional to the\n   * evidence actually lost rather than to the number of times the cap ran.\n   */\n  USER_SESSION_EVICTED = 'user_session_evicted',\n\n  /**\n   * `PROVIDER_OPERATION_CALL` from the provider operation executor — one row per OUTBOUND call to a\n   * third party, on both the success and the failure path.\n   *\n   * This is the application's record of what it sent to whom on whose behalf. Its silence is\n   * peculiarly misleading: an empty outbound trail reads as \"this deployment integrates with\n   * nothing\", which is a sentence somebody will believe.\n   */\n  PROVIDER_OPERATION_CALL = 'provider_operation_call',\n\n  /**\n   * The post-call credential-use stamp from the provider operation executor.\n   *\n   * ## Why this is on THIS counter even though its sink is not the audit service\n   *\n   * It writes to the tenant's own credential row rather than to `AuditLogsBackendService`, and it is\n   * still the identical observer-side loss shape: fire-and-forget, sink feature-detected, rejection\n   * swallowed, nothing counting the drops. The counter's subject is the LOSS OF A SECURITY\n   * OBSERVATION, not the identity of the store that was supposed to receive it — so a second counter\n   * for one site would fragment the alert without telling an operator anything the `observation`\n   * label does not already say.\n   *\n   * What it evidences is narrow and worth stating: whether a stored credential was ACCEPTED by the\n   * provider on last use. Losing it leaves a credential whose health is unknown, which surfaces\n   * later as an integration that fails with no record of when it started failing.\n   */\n  PROVIDER_CREDENTIAL_USE = 'provider_credential_use',\n\n  /**\n   * `HTTP_API_READ_THROUGH_ACCESS`, from BOTH emitters — see the enum's naming principle above.\n   *\n   * - `HttpApiResourceRepositoryBackendService.recordReadThroughAccess` — one observation per remote\n   *   round-trip, and the only tier that witnesses every one of them (repository-direct probes never\n   *   reach the services tier at all).\n   * - `ExternalDataPipelineRunBackendService.recordRunReadThroughAccess` — one observation per ETL\n   *   run.\n   *\n   * The evidence at stake is ATTRIBUTION: an HTTP_API read reaches a third party through a SHARED\n   * service principal, so this row is what carries the real initiating user through it. Without it\n   * the external system's own logs show one principal and nothing anywhere resolves it to a person.\n   */\n  HTTP_API_READ_THROUGH_ACCESS = 'http_api_read_through_access',\n}\n\n/**\n * WHY the observation never reached the audit pipeline.\n *\n * Three members, and they are genuinely different diagnoses rather than shades of one — see the\n * table in this module's header. `SERVICE_UNAVAILABLE` is a WIRING fault and is usually total and\n * permanent for the life of the process; the other two are runtime faults and are usually partial.\n * Merging them would leave an operator unable to tell \"this deployment audits nothing\" from \"the\n * audit store hiccupped twice\".\n */\nexport enum AuditObservationLossReason {\n  /** The audit service is unbound, or the specific `log*` method is absent on the bound instance. */\n  SERVICE_UNAVAILABLE = 'service_unavailable',\n  /** The emitting call threw synchronously — before any `.catch()` could make it fire-and-forget. */\n  EMISSION_THREW = 'emission_threw',\n  /** The emitting call returned a promise that rejected. */\n  EMISSION_REJECTED = 'emission_rejected',\n}\n\n/**\n * How often ONE `(observation, reason)` pair may produce a log line.\n *\n * Fifteen minutes: long enough that a permanently broken binding costs four lines an hour rather\n * than one per request, short enough that a NEW outage hours after an earlier one still announces\n * itself instead of being swallowed by a latch that never resets. A permanent latch was rejected for\n * exactly that reason — it makes the second incident invisible.\n */\nexport const LOSS_LOG_INTERVAL_MS = 15 * 60 * 1000;\n\n/** The narrow slice of {@link MetricsService} this seam needs. Structural, so a double is trivial. */\nexport interface AuditObservationLossMetricsRecorder {\n  recordAuditObservationDropped(params: { observation: string; reason: string }): void;\n}\n\n/**\n * A LAZY door to the recorder, for a site that does not hold one.\n *\n * Most emitters here are plain classes built with `new` (repository adapters, the provider executor)\n * or reach the container only through thunks their builder closes over. Each could resolve the\n * recorder itself — and each would then need its own `try`/`catch`, because a container resolving a\n * binding may throw and an observability failure must never reach the request. Five copies of that\n * guard is precisely the shape `.claude/rules/invariant-call-site-enumeration.md` says will be\n * applied at four of them, so the seam takes the thunk and does the wrapping once.\n *\n * Resolution happens ONLY when there is a loss to record. A site on the happy path never touches its\n * container, which is what makes handing this in unconditionally cheap.\n */\nexport type AuditObservationLossMetricsResolver = () => AuditObservationLossMetricsRecorder | undefined;\n\n/** The narrow slice of the logger this seam needs. Optional everywhere — see {@link emitAuditObservation}. */\nexport interface AuditObservationLossLogger {\n  error?: (message: string, context?: Record<string, unknown>) => void;\n}\n\n/** Process-local totals, keyed `<observation>:<reason>`. Not evidence — see the module header. */\nconst lossTotals = new Map<string, number>();\n/** Last log timestamp per `<observation>:<reason>`. Bounded by the enum cross-product (9 entries). */\nconst lastLoggedAt = new Map<string, number>();\n\n/**\n * Every loss recorded since this process started, as `<observation>:<reason>` → count.\n *\n * A COPY, so a caller cannot mutate the accumulator. Exists so the counting can be pinned without an\n * OTLP backend, and so a future health surface has a door that does not require one either. Read the\n * module header before treating the numbers as durable evidence: they are not.\n */\nexport function readAuditObservationLossTotals(): Record<string, number> {\n  return Object.fromEntries(lossTotals);\n}\n\n/** Test isolation only. Never called from production code. */\nexport function resetAuditObservationLossTotals(): void {\n  lossTotals.clear();\n  lastLoggedAt.clear();\n}\n\n/**\n * Record one lost observation. Never throws, under any circumstance.\n *\n * Exported so a site whose emission does not fit {@link emitAuditObservation}'s shape can still\n * contribute to the same counter rather than inventing a second one. Prefer the seam.\n */\nexport function recordAuditObservationLoss(params: {\n  observation: AuditObservationKind;\n  reason: AuditObservationLossReason;\n  /** The recorder itself, when the site already holds one (a container-injected service). */\n  metricsService?: AuditObservationLossMetricsRecorder;\n  /**\n   * A thunk to the recorder, when the site does not. Consulted only if `metricsService` is absent,\n   * and only on a loss — see {@link AuditObservationLossMetricsResolver}. Two fields rather than one\n   * union: a caller reading `metricsService: X | (() => X)` has to work out which one it holds, and\n   * the answer is a property of the CLASS, so it is better spelled at the field.\n   */\n  metricsResolver?: AuditObservationLossMetricsResolver;\n  logger?: AuditObservationLossLogger;\n  error?: unknown;\n  context?: Record<string, unknown>;\n}): void {\n  // The recorder is the LAST thing that may fail the request it observes: a metric backend that\n  // throws, or a logger that throws, would defeat the entire purpose of the fire-and-forget contract\n  // this seam exists to preserve. Everything below is inside one boundary for that reason.\n  try {\n    const key = `${params.observation}:${params.reason}`;\n    lossTotals.set(key, (lossTotals.get(key) ?? 0) + 1);\n\n    // Metrics FIRST. It is the durable, rate-carrying channel, and it must be incremented even for\n    // the drops the throttle below decides not to log — otherwise the throttle would silently\n    // suppress the count as well as the line, which is the defect one layer up.\n    //\n    // Feature-DETECTED rather than optional-chained on the object, and for the reason this whole\n    // module exists: a container that answers every symbol with a stub (the shape several partial\n    // test containers in this package genuinely have) yields a truthy `metricsService` whose method\n    // is absent, so `?.` on the OBJECT still calls `undefined(...)` and throws. The outer catch\n    // would contain it, but a swallowed TypeError looks exactly like a swallowed real defect — and\n    // it would take the log line down with it, leaving the loss silent again.\n    const metricsService = params.metricsService ?? resolveLossMetricsRecorder(params.metricsResolver);\n    if (typeof metricsService?.recordAuditObservationDropped === 'function') {\n      metricsService.recordAuditObservationDropped({\n        observation: params.observation,\n        reason: params.reason,\n      });\n    }\n\n    const now = Date.now();\n    const previous = lastLoggedAt.get(key);\n    if (previous !== undefined && now - previous < LOSS_LOG_INTERVAL_MS) return;\n    lastLoggedAt.set(key, now);\n\n    params.logger?.error?.('A security audit observation was DROPPED before it reached the audit pipeline', {\n      // `reason` is the slug an alert rule and a log query both key on; keep it first and stable.\n      reason: 'audit_observation_dropped',\n      observation: params.observation,\n      lossReason: params.reason,\n      // The running total makes ONE throttled line carry the volume the suppressed lines would have.\n      occurrencesSinceProcessStart: lossTotals.get(key),\n      logIntervalMs: LOSS_LOG_INTERVAL_MS,\n      ...(params.error === undefined ? {} : { error: describeLossError(params.error) }),\n      ...(params.context ?? {}),\n    });\n  } catch {\n    /* An observability failure must never be able to fail the request it observes. */\n  }\n}\n\n/**\n * Emit one fire-and-forget audit observation, counting it if it is lost.\n *\n * ## The contract, which is the whole point\n *\n * **This function never throws and never returns a promise.** Not on an absent service, not on a\n * synchronous throw, not on a rejection, and not on a metrics or logger failure. Callers rely on it\n * to preserve the property their own JSDoc promises: the observation cannot fail the request.\n *\n * @param params.emit The emitting call, or `undefined` when the audit service or its method is\n *   absent. Passing `undefined` is how a site reports {@link AuditObservationLossReason.SERVICE_UNAVAILABLE}\n *   — the feature detection stays at the site because the method name differs per observation, and a\n *   generic reflective lookup here would trade a compile-time error for a runtime one.\n */\nexport function emitAuditObservation(params: {\n  observation: AuditObservationKind;\n  emit: (() => unknown) | undefined;\n  metricsService?: AuditObservationLossMetricsRecorder;\n  /** See {@link recordAuditObservationLoss}. Never called unless there IS a loss. */\n  metricsResolver?: AuditObservationLossMetricsResolver;\n  logger?: AuditObservationLossLogger;\n  context?: Record<string, unknown>;\n}): void {\n  const loss = (reason: AuditObservationLossReason, error?: unknown): void =>\n    recordAuditObservationLoss({\n      observation: params.observation,\n      reason,\n      metricsService: params.metricsService,\n      metricsResolver: params.metricsResolver,\n      logger: params.logger,\n      error,\n      context: params.context,\n    });\n\n  try {\n    if (!params.emit) {\n      loss(AuditObservationLossReason.SERVICE_UNAVAILABLE);\n      return;\n    }\n\n    let result: unknown;\n    try {\n      result = params.emit();\n    } catch (error) {\n      // A `log*` method that is absent on a partially-mocked double throws a TypeError HERE —\n      // synchronously, before any `.catch()` could attach. That is the shape the feature detection at\n      // each site exists to pre-empt; this catch is what keeps a site that forgets it from crashing.\n      loss(AuditObservationLossReason.EMISSION_THREW, error);\n      return;\n    }\n\n    // Optional-chained, because an audit method is free to be synchronous (and every test double\n    // returning `undefined` is). A non-thenable result is a successful emission, not a loss.\n    const thenable = result as { catch?: (handler: (error: unknown) => void) => unknown } | null | undefined;\n    if (typeof thenable?.catch !== 'function') return;\n    thenable.catch((error) => loss(AuditObservationLossReason.EMISSION_REJECTED, error));\n  } catch {\n    /* Belt and braces: nothing in this seam may reach the caller. */\n  }\n}\n\n/**\n * Ask a site's thunk for the recorder, and treat any refusal as \"no recorder\".\n *\n * Its own `try`, INSIDE the caller's: a container that throws while resolving a binding must not be\n * able to take the LOG channel down with it. Degrading a loss to its log-only form is the correct\n * direction — the whole point of this module is that an observability gap is never a reason to\n * refuse — whereas letting the throw escape to the outer `catch` would silence both channels for the\n * one event that most needs saying.\n */\nfunction resolveLossMetricsRecorder(\n  resolver: AuditObservationLossMetricsResolver | undefined,\n): AuditObservationLossMetricsRecorder | undefined {\n  if (typeof resolver !== 'function') return undefined;\n  try {\n    return resolver();\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * A log-safe description of whatever was thrown.\n *\n * Deliberately local rather than routed through `describeCaughtError`: this module sits UNDER the\n * error subsystem in the dependency order (the error builder's own failures are observations this\n * seam records), and importing upward would make an observability module depend on the layer it\n * observes. The shape is a strict subset of what `describeCaughtError` produces, so a log query\n * reading `error.message` works against both.\n */\nfunction describeLossError(error: unknown): { message: string; name?: string } {\n  if (error instanceof Error) return { message: error.message, name: error.name };\n  return { message: typeof error === 'string' ? error : String(error) };\n}\n"]}

package/dist/esm/monitoring/observability/models/observability.backend.schemas.d.ts

@@ -27,5 +27,6 @@ export interface MetricDefinitions {
     auditTamperDetectedTotal: any;
     auditIntegrityAssuranceDegradedTotal: any;
     auditStoreFailureTotal: any;
+    auditObservationDroppedTotal: any;
 }
 //# sourceMappingURL=observability.backend.schemas.d.ts.map

package/dist/esm/monitoring/observability/models/observability.backend.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability.backend.schemas.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/models/observability.backend.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAGhC,0BAA0B,EAAE,GAAG,CAAC;IAChC,4BAA4B,EAAE,GAAG,CAAC;IAClC,6BAA6B,EAAE,GAAG,CAAC;IACnC,mBAAmB,EAAE,GAAG,CAAC;IACzB,iCAAiC,EAAE,GAAG,CAAC;IAMvC,uBAAuB,EAAE,GAAG,CAAC;IAS7B,qBAAqB,EAAE,GAAG,CAAC;IAU3B,wBAAwB,EAAE,GAAG,CAAC;IAU9B,oCAAoC,EAAE,GAAG,CAAC;IAU1C,sBAAsB,EAAE,GAAG,CAAC;CAC7B"}
+{"version":3,"file":"observability.backend.schemas.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/models/observability.backend.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB;IAGhC,0BAA0B,EAAE,GAAG,CAAC;IAChC,4BAA4B,EAAE,GAAG,CAAC;IAClC,6BAA6B,EAAE,GAAG,CAAC;IACnC,mBAAmB,EAAE,GAAG,CAAC;IACzB,iCAAiC,EAAE,GAAG,CAAC;IAMvC,uBAAuB,EAAE,GAAG,CAAC;IAS7B,qBAAqB,EAAE,GAAG,CAAC;IAU3B,wBAAwB,EAAE,GAAG,CAAC;IAU9B,oCAAoC,EAAE,GAAG,CAAC;IAU1C,sBAAsB,EAAE,GAAG,CAAC;IAW5B,4BAA4B,EAAE,GAAG,CAAC;CACnC"}

package/dist/esm/monitoring/observability/models/observability.backend.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"observability.backend.schemas.js","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/models/observability.backend.schemas.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Observability metric definitions consumed by `metrics.service.ts`.\n *\n * Only the metrics with LIVE producers remain: the data-seeding counters\n * (fired by the data-seed dispatcher engines + shared ledger writers) and the\n * M2M outbound-webhook counter (fired by the delivery batch worker). The former\n * HTTP / DB / auth / cache / session / quota / websocket / error definitions\n * were removed in Slice 2 Phase 3 along with the dead, never-registered\n * observability middleware that was their only caller: HTTP traces +\n * `http.server.duration` metrics now come from the OTLP preload's\n * auto-instrumentation (bounded, semconv attributes) rather than a hand-rolled\n * middleware that tagged every series with unbounded `organization_id` /\n * `user_id` labels (edge case E13).\n *\n * History: the self-hosted Jaeger/Prometheus `TelemetryService`,\n * `ObservabilityConfig`, and `TelemetryProviders` were deleted in Phase 1;\n * the Prometheus-era middleware + the dead `TracerService` in Phase 3.\n */\nexport interface MetricDefinitions {\n  // Data Seeding (Phase 6.D / F-17 — Prom-style operator metrics).\n  // See `metrics.service.ts` for descriptions.\n  dataSeedingLazyC1CacheHits: any;\n  dataSeedingLazyC1CacheMisses: any;\n  dataSeedingThunderHerdBowouts: any;\n  dataSeedingRunTotal: any;\n  dataSeedingAdminListSeedsDuration: any;\n\n  // M2M Outbound Webhook Delivery (Phase 5 / Step 17 — Prom-style\n  // operator metrics). Single counter covering every worker outcome\n  // at terminal or intermediate return; see `metrics.service.ts`\n  // (`recordM2MWebhookDeliveryOutcome`) for labels + semantics.\n  m2mWebhookDeliveryTotal: any;\n\n  // Compliance Audit-Log Sink failures (Phase 5 / F6 — Prom-style operator\n  // metric). One counter incremented whenever a Layer-2 provider audit sink\n  // throws while recording an event; the composite (`CompositeAuditLogSink`)\n  // isolates the failure so the business op is unaffected, but this makes the\n  // otherwise-swallowed failure OBSERVABLE. Labelled by `provider` (the provider\n  // ref — immudb, a SIEM, …); bounded, low cardinality. See `metrics.service.ts`\n  // (`recordAuditSinkFailure`).\n  auditSinkFailureTotal: any;\n\n  // Compliance Audit-Log TAMPER detections (Prom-style operator metric). One\n  // counter incremented when a tamper-evident audit provider (immudb) PROVES its\n  // store was rolled back / tampered between restarts (a durable-state consistency\n  // proof failure). DISTINCT from `auditSinkFailureTotal` on purpose: a transient\n  // write miss is backfilled by the reconciler, whereas a proven rollback of the\n  // audit ledger is a compliance incident that must page a human. Labelled by\n  // `provider`; bounded, low cardinality. See `metrics.service.ts`\n  // (`recordAuditTamperDetected`).\n  auditTamperDetectedTotal: any;\n\n  // Compliance Audit-Log assurance DEGRADATIONS. Incremented when a tamper-evident\n  // audit provider drops from full cross-restart tamper-evidence to a weaker level\n  // (ephemeral mode / corrupt anchor / un-pinned identity change / per-op proof\n  // failure). DISTINCT from a PROVEN tamper (`auditTamperDetectedTotal` → page) and a\n  // write hiccup (`auditSinkFailureTotal`): a degradation means a FUTURE tamper may go\n  // undetected, so it is alertable but non-latching. Labelled by `provider` + `reason`\n  // (a small fixed slug set). See `metrics.service.ts`\n  // (`recordAuditIntegrityAssuranceDegraded`).\n  auditIntegrityAssuranceDegradedTotal: any;\n\n  // Compliance Audit-Log LAYER-1 (authoritative DB store) write failures (A-12). One counter\n  // incremented when `AuditLogsBackendService._createAuditLog` throws while persisting the authoritative\n  // audit row. DISTINCT from `auditSinkFailureTotal` (a Layer-2 provider-sink hiccup the reconciler\n  // backfills): a Layer-1 failure means the PRIMARY audit record itself was not persisted — the most\n  // severe \"we think we're auditing but we aren't\" state, otherwise invisible on the fire-and-forget\n  // path. Label-free (the authoritative store has no provider dimension); bounded, single series. See\n  // `metrics.service.ts` (`recordAuditStoreFailure`); the alert rule is specified in\n  // `.claude/plans/alerting-system-design-analysis.md` Appendix D.\n  auditStoreFailureTotal: any;\n}\n"]}
+{"version":3,"file":"observability.backend.schemas.js","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/models/observability.backend.schemas.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Observability metric definitions consumed by `metrics.service.ts`.\n *\n * Only the metrics with LIVE producers remain: the data-seeding counters\n * (fired by the data-seed dispatcher engines + shared ledger writers) and the\n * M2M outbound-webhook counter (fired by the delivery batch worker). The former\n * HTTP / DB / auth / cache / session / quota / websocket / error definitions\n * were removed in Slice 2 Phase 3 along with the dead, never-registered\n * observability middleware that was their only caller: HTTP traces +\n * `http.server.duration` metrics now come from the OTLP preload's\n * auto-instrumentation (bounded, semconv attributes) rather than a hand-rolled\n * middleware that tagged every series with unbounded `organization_id` /\n * `user_id` labels (edge case E13).\n *\n * History: the self-hosted Jaeger/Prometheus `TelemetryService`,\n * `ObservabilityConfig`, and `TelemetryProviders` were deleted in Phase 1;\n * the Prometheus-era middleware + the dead `TracerService` in Phase 3.\n */\nexport interface MetricDefinitions {\n  // Data Seeding (Phase 6.D / F-17 — Prom-style operator metrics).\n  // See `metrics.service.ts` for descriptions.\n  dataSeedingLazyC1CacheHits: any;\n  dataSeedingLazyC1CacheMisses: any;\n  dataSeedingThunderHerdBowouts: any;\n  dataSeedingRunTotal: any;\n  dataSeedingAdminListSeedsDuration: any;\n\n  // M2M Outbound Webhook Delivery (Phase 5 / Step 17 — Prom-style\n  // operator metrics). Single counter covering every worker outcome\n  // at terminal or intermediate return; see `metrics.service.ts`\n  // (`recordM2MWebhookDeliveryOutcome`) for labels + semantics.\n  m2mWebhookDeliveryTotal: any;\n\n  // Compliance Audit-Log Sink failures (Phase 5 / F6 — Prom-style operator\n  // metric). One counter incremented whenever a Layer-2 provider audit sink\n  // throws while recording an event; the composite (`CompositeAuditLogSink`)\n  // isolates the failure so the business op is unaffected, but this makes the\n  // otherwise-swallowed failure OBSERVABLE. Labelled by `provider` (the provider\n  // ref — immudb, a SIEM, …); bounded, low cardinality. See `metrics.service.ts`\n  // (`recordAuditSinkFailure`).\n  auditSinkFailureTotal: any;\n\n  // Compliance Audit-Log TAMPER detections (Prom-style operator metric). One\n  // counter incremented when a tamper-evident audit provider (immudb) PROVES its\n  // store was rolled back / tampered between restarts (a durable-state consistency\n  // proof failure). DISTINCT from `auditSinkFailureTotal` on purpose: a transient\n  // write miss is backfilled by the reconciler, whereas a proven rollback of the\n  // audit ledger is a compliance incident that must page a human. Labelled by\n  // `provider`; bounded, low cardinality. See `metrics.service.ts`\n  // (`recordAuditTamperDetected`).\n  auditTamperDetectedTotal: any;\n\n  // Compliance Audit-Log assurance DEGRADATIONS. Incremented when a tamper-evident\n  // audit provider drops from full cross-restart tamper-evidence to a weaker level\n  // (ephemeral mode / corrupt anchor / un-pinned identity change / per-op proof\n  // failure). DISTINCT from a PROVEN tamper (`auditTamperDetectedTotal` → page) and a\n  // write hiccup (`auditSinkFailureTotal`): a degradation means a FUTURE tamper may go\n  // undetected, so it is alertable but non-latching. Labelled by `provider` + `reason`\n  // (a small fixed slug set). See `metrics.service.ts`\n  // (`recordAuditIntegrityAssuranceDegraded`).\n  auditIntegrityAssuranceDegradedTotal: any;\n\n  // Compliance Audit-Log LAYER-1 (authoritative DB store) write failures (A-12). One counter\n  // incremented when `AuditLogsBackendService._createAuditLog` throws while persisting the authoritative\n  // audit row. DISTINCT from `auditSinkFailureTotal` (a Layer-2 provider-sink hiccup the reconciler\n  // backfills): a Layer-1 failure means the PRIMARY audit record itself was not persisted — the most\n  // severe \"we think we're auditing but we aren't\" state, otherwise invisible on the fire-and-forget\n  // path. Label-free (the authoritative store has no provider dimension); bounded, single series. See\n  // `metrics.service.ts` (`recordAuditStoreFailure`); the alert rule is specified in\n  // `.claude/plans/alerting-system-design-analysis.md` Appendix D.\n  auditStoreFailureTotal: any;\n\n  // Security audit observations DROPPED before the audit pipeline ever saw them. Incremented by the\n  // shared fire-and-forget seam (`audit-observation-emission.backend.ts`) whenever an observation is\n  // lost because the audit service is unbound / its `log*` method is absent, the call threw\n  // synchronously, or the returned promise rejected. DISTINCT from `auditStoreFailureTotal`, which\n  // counts the Layer-1 STORE refusing a write it did receive: this counts the emission never getting\n  // that far, which is the shape no existing control could see. Without it a period with no recorded\n  // operator crossings is indistinguishable from a period with a broken sink. Labelled by\n  // `observation` (which security event was lost) × `reason` (which of the three loss shapes);\n  // bounded — 3 × 3 series today. See `metrics.service.ts` (`recordAuditObservationDropped`).\n  auditObservationDroppedTotal: any;\n}\n"]}

package/dist/esm/monitoring/observability/services/metrics.service.d.ts

@@ -168,5 +168,26 @@ export declare class MetricsService {
      * store has no provider dimension. Alert rule: `alerting-system-design-analysis.md` Appendix D.
      */
     recordAuditStoreFailure(): void;
+    /**
+     * A fire-and-forget security audit observation was DROPPED before it reached the audit pipeline.
+     * Fired by the shared emission seam (`audit-observation-emission.backend.ts`), which every such
+     * observation routes through, so a new observation is counted the day it lands.
+     *
+     * DISTINCT from {@link recordAuditStoreFailure}, and the distinction is the reason this counter
+     * exists: that one fires INSIDE `_createAuditLog`, so it only ever sees an emission that reached
+     * the audit service. The three shapes counted here — an unbound service or absent `log*` method, a
+     * synchronous throw, a rejected promise — never get that far, and were previously invisible.
+     * Merging them into one counter would let a total wiring outage hide behind a store hiccup.
+     *
+     * Synchronous, never throws (the global meter is a no-op without the OTLP preload — which is why
+     * the seam ALSO logs, at a throttled `error`).
+     *
+     * @param params.observation - `AuditObservationKind` member — WHICH security event was lost.
+     * @param params.reason - `AuditObservationLossReason` member — WHICH of the three loss shapes.
+     */
+    recordAuditObservationDropped(params: {
+        observation: string;
+        reason: string;
+    }): void;
 }
 //# sourceMappingURL=metrics.service.d.ts.map

package/dist/esm/monitoring/observability/services/metrics.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.service.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/services/metrics.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;;;GAUG;AACH,qBACa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,kBAAkB,CAAoB;;IAO9C,OAAO,CAAC,iBAAiB;IAqHzB;;;;OAIG;IACI,6BAA6B,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO1F;;;;OAIG;IACI,8BAA8B,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO3F;;;;;;;;OAQG;IACI,kCAAkC,CAAC,MAAM,EAAE;QAChD,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,sBAAsB,GAAG,oBAAoB,CAAC;KACvD,GAAG,IAAI;IAQR;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,oBAAoB,CAAC,MAAM,EAAE;QAClC,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAUR;;;;;;;;;;;;;;;OAeG;IACI,uCAAuC,CAAC,MAAM,EAAE;QACrD,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAmCR;;;;;;;;;;;;;;OAcG;IACI,+BAA+B,CAAC,MAAM,EAAE;QAC7C,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EACH,WAAW,GACX,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,wBAAwB,CAAC;KAC9B,GAAG,IAAI;IAWR;;;;;;;;OAQG;IACI,sBAAsB,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMpE;;;;;;;;;OASG;IACI,yBAAyB,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMvE;;;;;;;;;;OAUG;IACI,qCAAqC,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOnG;;;;;;;;OAQG;IACI,uBAAuB,IAAI,IAAI;CAGvC"}
+{"version":3,"file":"metrics.service.d.ts","sourceRoot":"","sources":["../../../../../../src/monitoring/observability/services/metrics.service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;;;;GAUG;AACH,qBACa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,kBAAkB,CAAoB;;IAO9C,OAAO,CAAC,iBAAiB;IAsIzB;;;;OAIG;IACI,6BAA6B,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO1F;;;;OAIG;IACI,8BAA8B,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO3F;;;;;;;;OAQG;IACI,kCAAkC,CAAC,MAAM,EAAE;QAChD,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,sBAAsB,GAAG,oBAAoB,CAAC;KACvD,GAAG,IAAI;IAQR;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,oBAAoB,CAAC,MAAM,EAAE;QAClC,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAUR;;;;;;;;;;;;;;;OAeG;IACI,uCAAuC,CAAC,MAAM,EAAE;QACrD,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAmCR;;;;;;;;;;;;;;OAcG;IACI,+BAA+B,CAAC,MAAM,EAAE;QAC7C,KAAK,EAAE,aAAa,CAAC;QACrB,OAAO,EACH,WAAW,GACX,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,GACrB,wBAAwB,CAAC;KAC9B,GAAG,IAAI;IAWR;;;;;;;;OAQG;IACI,sBAAsB,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMpE;;;;;;;;;OASG;IACI,yBAAyB,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMvE;;;;;;;;;;OAUG;IACI,qCAAqC,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOnG;;;;;;;;OAQG;IACI,uBAAuB,IAAI,IAAI;IAItC;;;;;;;;;;;;;;;;OAgBG;IACI,6BAA6B,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAM5F"}

package/dist/esm/monitoring/observability/services/metrics.service.js

@@ -122,6 +122,21 @@ let MetricsService = class MetricsService {
             auditStoreFailureTotal: this.meter.createCounter('audit_store_failure_total', {
                 description: 'Compliance audit-log Layer-1 authoritative DB store write failures (one per _createAuditLog persist throw)',
             }),
+            // ─── Security audit observations DROPPED before the pipeline saw them ────
+            // A fire-and-forget security observation (an operator tenant crossing, an authorization
+            // refusal, a platform-access grant transition) never reached `AuditLogsBackendService` at all:
+            // the service was unbound or its `log*` method absent, the call threw synchronously, or the
+            // returned promise rejected. DISTINCT from `audit_store_failure_total`, which fires INSIDE
+            // `_createAuditLog` and therefore only sees emissions that got that far — the drops counted
+            // here are exactly the ones it structurally cannot see. Fire-and-forget is deliberate and
+            // stays (an observation must never fail the request it observes), so without this counter the
+            // loss is completely silent and "no operator crossings this week" is indistinguishable from
+            // "the audit service has been unbound since Tuesday". Operators alert on
+            //   increase(audit_observation_dropped_total[15m]) > 0
+            // Cardinality: 3 `observation` × 3 `reason` = 9 series today, both label sets closed enums.
+            auditObservationDroppedTotal: this.meter.createCounter('audit_observation_dropped_total', {
+                description: 'Security audit observations dropped before reaching the audit pipeline (service unavailable / emission threw / emission rejected)',
+            }),
         };
     }
     // ---------------------------------------------------------------------------
@@ -339,6 +354,29 @@ let MetricsService = class MetricsService {
     recordAuditStoreFailure() {
         this.metricsDefinitions.auditStoreFailureTotal.add(1);
     }
+    /**
+     * A fire-and-forget security audit observation was DROPPED before it reached the audit pipeline.
+     * Fired by the shared emission seam (`audit-observation-emission.backend.ts`), which every such
+     * observation routes through, so a new observation is counted the day it lands.
+     *
+     * DISTINCT from {@link recordAuditStoreFailure}, and the distinction is the reason this counter
+     * exists: that one fires INSIDE `_createAuditLog`, so it only ever sees an emission that reached
+     * the audit service. The three shapes counted here — an unbound service or absent `log*` method, a
+     * synchronous throw, a rejected promise — never get that far, and were previously invisible.
+     * Merging them into one counter would let a total wiring outage hide behind a store hiccup.
+     *
+     * Synchronous, never throws (the global meter is a no-op without the OTLP preload — which is why
+     * the seam ALSO logs, at a throttled `error`).
+     *
+     * @param params.observation - `AuditObservationKind` member — WHICH security event was lost.
+     * @param params.reason - `AuditObservationLossReason` member — WHICH of the three loss shapes.
+     */
+    recordAuditObservationDropped(params) {
+        this.metricsDefinitions.auditObservationDroppedTotal.add(1, {
+            observation: params.observation,
+            reason: params.reason,
+        });
+    }
 };
 MetricsService = __decorate([
     injectable(),