@geonosis/observability 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import * as better_result from 'better-result';
+import { Result } from 'better-result';
+import { A as Attributes, E as ErrorSink, L as LastEventRecord, T as Tracer, S as SpanRecord } from './ports-Ct5eq-HS.js';
+export { a as AttributeValue, C as CaptureReceipt, b as SinkFailure } from './ports-Ct5eq-HS.js';
+
+/**
+ * The vocabulary, enforced.
+ *
+ * Two spellings of the same rules, on purpose. `parseAttributes` is structural and has no
+ * dependencies, so the sinks in this package validate without importing anything — and
+ * `attributesSchema(z)` builds the same rules over the CALLER's zod, because both consumers run
+ * different copies of it (4.2.0, 4.4.3 and 4.5.4 measured across the two trees in
+ * `docs/ports-events-inventory-2026-08-30.md`) and neither `@geonosis/events` nor
+ * `@geonosis/integrations` will import one. A test drives every case through both and asserts they
+ * agree; two validators that could disagree are worse than one.
+ */
+declare const ATTRIBUTE_KEYS: readonly ["actor", "envelopeId", "release", "runtime", "service", "tenant"];
+type AttributeKey = (typeof ATTRIBUTE_KEYS)[number];
+declare const SPAN_NAME_CONVENTION = "A span name is `<area>.<action>`, lowercase, at least two dot-separated segments, letters and digits with dashes inside a segment: `queue.handle-batch`, `db.cell.query`. A name is a dimension in every trace query, so `queue.handle-batch` and `Queue Handle Batch` in one tree are two dimensions where the author meant one.";
+declare const InvalidAttributes_base: better_result.TaggedErrorClass<"InvalidAttributes">;
+declare class InvalidAttributes extends InvalidAttributes_base<{
+    message: string;
+}> {
+}
+declare const parseAttributes: (value: unknown) => Result<Attributes, InvalidAttributes>;
+/** What a caller gets back: enough of a schema to embed, and nothing this package had to import. */
+type ZodSchema = {
+    safeParse: (value: unknown) => {
+        data?: unknown;
+        success: boolean;
+    };
+};
+/**
+ * The same vocabulary as a schema, built over the caller's zod, for a consumer whose contract layer
+ * already speaks schemas. The shape is declared so the schema is introspectable; every rule that is
+ * not a shape — a blank service, a tenant that is a person, an `extra` that shadows the vocabulary —
+ * comes from `problemsOf`, the one function `parseAttributes` also uses. Two validators that could
+ * disagree would be worse than one, so there is only one set of rules and two doors to it.
+ */
+declare const attributesSchema: (z: unknown) => ZodSchema;
+
+/**
+ * At-least-once in, at-most-once counted.
+ *
+ * Cloudflare Queues redelivers, and during.day recognises a redelivery with
+ * `handleQueue({ seen: (id) => hasAuditEntryForEvent(db, { eventId: id }) })` — a database read.
+ * The store is the consumer's (a Map in one isolate, an audit table in a cell, a KV namespace at an
+ * edge), so only the COUNTING is portable and the store arrives as two functions.
+ *
+ * The rule that matters is the one about failure: an envelope whose capture FAILED is not
+ * remembered. Remembering it before the sink answered would buy at-most-once by losing
+ * at-least-once — one transport error and that envelope is silent for ever.
+ */
+type DedupeStore = {
+    /** Record that this envelope was filed, and under which id. */
+    remember: (envelopeId: string, id: string) => Promise<void> | void;
+    /** The id this envelope was filed under before, or undefined if it has not been. */
+    seen: (envelopeId: string) => Promise<string | undefined> | string | undefined;
+};
+declare const withDedupe: (sink: ErrorSink, store?: DedupeStore) => ErrorSink;
+
+/**
+ * The producer half of the file contract `geonosis-doctor`'s `observability` check reads.
+ *
+ * The doctor imports nothing of this package — it parses `{ at, id, sink }` off disk — because a
+ * check that needed the library it checks cannot run in the tree where the library is missing,
+ * which is the first case it exists to find. So the shape lives here and the reader lives there,
+ * and both are tested against the same field names.
+ *
+ * The WRITER is injected. A file is a Node fact; on workerd the same record goes to a KV namespace
+ * or a D1 row, and a package that reached for `node:fs` would not load in the runtime that has most
+ * of the errors.
+ */
+declare const withLastEvent: (sink: ErrorSink, record: (event: LastEventRecord) => Promise<void>, now?: () => number) => ErrorSink;
+
+/**
+ * The sink tests, the probe and a no-key deployment all read.
+ *
+ * dielime's LLM seam is the posture: its no-key path is a real deterministic implementation that
+ * runs the whole loop, not a null object. during.day's `silentAnalyticsSink` is the other posture,
+ * and its own comment has to argue it is "not a null object hiding a mistake". A sink you can read
+ * needs no such argument.
+ */
+type CapturedError = {
+    at: number;
+    attributes: Attributes;
+    error: Error;
+    id: string;
+};
+type MemorySink = ErrorSink & {
+    readonly captured: readonly CapturedError[];
+    clear: () => void;
+    readonly flushes: number;
+};
+/** The envelope id when there is one, so a redelivery lands on the row its first delivery made. */
+declare const idFor: (attributes: Attributes) => string;
+declare const createMemorySink: (options?: {
+    now?: () => number;
+}) => MemorySink;
+/**
+ * during.day's `silentAnalyticsSink` with the `console.info` taken out: it answers ok and keeps
+ * nothing. Shipped ON PURPOSE, because it is the production path in both consumers whenever no key
+ * is configured — and because `--prove` must be able to catch it. A probe that could not tell this
+ * apart from a real sink would be the fifth lying instrument.
+ */
+declare const createSwallowingSink: () => ErrorSink;
+
+/**
+ * D-029 for a sink: every gate ships its own falsification probe.
+ *
+ * The ratchet compares a number against a number and cannot tell a counter that found nothing from
+ * a counter that CAN find nothing. A sink is worse — it answers `ok` either way, and during.day's
+ * `silentAnalyticsSink` answers `ok` in production whenever no key is set. So the probe plants an
+ * error under an id nothing else in the world has, and then goes and LOOKS.
+ */
+type ObservabilityVerdict = 'cannot-fail' | 'cannot-measure' | 'misread' | 'proven';
+type SinkProbe = {
+    /** Whatever the probe opened — a server, a client, a connection. Closed whatever the verdict. */
+    close?: () => Promise<void>;
+    /** The sink, in a verdict. */
+    kind: string;
+    /**
+     * Every id this sink can see right now. EMPTY is the answer that separates a swallower from a
+     * misfiler: a sink holding nothing at all cannot fail, and one holding something that is not the
+     * plant filed it under an id nobody was given.
+     */
+    seen: (traceId: string) => Promise<readonly string[]>;
+    sink: ErrorSink;
+};
+type ObservabilityProof = {
+    /** What the probe could see when it gave up. Named in a MISREAD, because it is the evidence. */
+    found?: readonly string[];
+    kind: string;
+    reason?: string;
+    traceId?: string;
+    verdict: ObservabilityVerdict;
+};
+declare const PROBE_SERVICE = "geonosis-observability-probe";
+/** The memory sink and a way to read it — what the kit's own gate and `--sink memory` prove over. */
+declare const memoryProbe: () => SinkProbe & {
+    sink: MemorySink;
+};
+declare const proveObservability: ({ attributes, probe, timeoutMs, }: {
+    /** What the plant says about itself. Defaults to this probe's own service name. */
+    attributes?: Partial<Attributes>;
+    /** Absent means nothing is configured, which is a refusal and never a pass. */
+    probe?: SinkProbe;
+    timeoutMs?: number;
+}) => Promise<ObservabilityProof>;
+declare const formatProof: (proof: ObservabilityProof) => string;
+/** PROVEN is the only pass. Two, never one: a refusal is not the same as a finding. */
+declare const exitCodeOf: (proof: ObservabilityProof) => number;
+
+declare const isSpanName: (name: string) => boolean;
+
+type MemoryTracer = Tracer & {
+    clear: () => void;
+    readonly spans: readonly SpanRecord[];
+};
+/**
+ * A tracer records; it does not decide. The body's value comes back untouched and the body's throw
+ * goes back up untouched — a tracer that swallowed one would make a failed request answer 200,
+ * which is the third lying instrument of #42 rebuilt on purpose.
+ *
+ * Attributes that break the vocabulary are recorded as given rather than refused, for the same
+ * reason a span name is: instrumentation must not be the thing that takes a request down. The sink
+ * refuses; the tracer reports.
+ */
+declare const createMemoryTracer: (options?: {
+    now?: () => number;
+}) => MemoryTracer;
+/** Whether a tracer's attributes would have been accepted by a sink. For tests and for a probe. */
+declare const spanAttributesAreValid: (span: SpanRecord) => boolean;
+
+/**
+ * A dedupe key that survives the vendor.
+ *
+ * Measured against `posthog-node@5.50.0` over a stub server: a `uuid` that is not a valid UUID is
+ * REPLACED with a generated one, silently. during.day's envelope ids are `crypto.randomUUID()` so
+ * its dedupe works; a consumer whose ids are prefixed (`evt_…`, a ULID, a nanoid, a Medusa
+ * `order_01H…`) would hand over a dedupe key that never arrives and read every redelivery as a new
+ * incident, for ever, with nothing anywhere saying so.
+ *
+ * So an id that is already a UUID goes through untouched — during.day's shape, unchanged — and one
+ * that is not becomes a UUIDv5 derived from it: same envelope, same uuid, every time, in every
+ * process. The original goes on the wire as a property, because a stable uuid nobody can guess is
+ * not something a human greps for.
+ */
+declare const isUuid: (value: string) => boolean;
+/**
+ * UUIDv5 of `value`, under this package's namespace unless another is named. Deterministic across
+ * processes and runtimes — the namespace is a parameter so the published RFC 4122 §4.3 vectors can
+ * be run against it: self-consistency would be satisfied by any hash at all, and two services
+ * deriving an id for the same envelope have to agree even when one of them is not running this code.
+ */
+declare const uuidFrom: (value: string, inNamespace?: string) => Promise<string>;
+declare const randomUuid: () => string;
+/**
+ * The uuid a vendor is given for this envelope: the envelope id when it already is one, a stable
+ * derivation when it is not, a fresh one when there is no envelope at all.
+ */
+declare const uuidForEnvelope: (envelopeId: string | undefined) => Promise<string>;
+
+export { ATTRIBUTE_KEYS, type AttributeKey, Attributes, type CapturedError, type DedupeStore, ErrorSink, InvalidAttributes, LastEventRecord, type MemorySink, type MemoryTracer, type ObservabilityProof, type ObservabilityVerdict, PROBE_SERVICE, SPAN_NAME_CONVENTION, type SinkProbe, SpanRecord, Tracer, type ZodSchema, attributesSchema, createMemorySink, createMemoryTracer, createSwallowingSink, exitCodeOf, formatProof, idFor, isSpanName, isUuid, memoryProbe, parseAttributes, proveObservability, randomUuid, spanAttributesAreValid, uuidForEnvelope, uuidFrom, withDedupe, withLastEvent };

package/dist/index.js

@@ -0,0 +1,145 @@
+import {
+  PROBE_SERVICE,
+  createMemorySink,
+  createSwallowingSink,
+  exitCodeOf,
+  formatProof,
+  idFor,
+  memoryProbe,
+  proveObservability
+} from "./chunk-UFR2R2VM.js";
+import {
+  ATTRIBUTE_KEYS,
+  InvalidAttributes,
+  SPAN_NAME_CONVENTION,
+  SinkFailure,
+  attributesSchema,
+  isUuid,
+  parseAttributes,
+  randomUuid,
+  uuidForEnvelope,
+  uuidFrom
+} from "./chunk-2ZTQU3OO.js";
+
+// src/dedupe.ts
+import { Result } from "better-result";
+var inMemoryStore = () => {
+  const rows = /* @__PURE__ */ new Map();
+  return {
+    remember: (envelopeId, id) => {
+      rows.set(envelopeId, id);
+    },
+    seen: (envelopeId) => rows.get(envelopeId)
+  };
+};
+var withDedupe = (sink, store = inMemoryStore()) => ({
+  capture: async (error, attributes) => {
+    const parsed = parseAttributes(attributes);
+    if (parsed.isErr()) {
+      return Result.err(
+        new SinkFailure({
+          cause: parsed.error,
+          message: parsed.error.message,
+          sink: `${sink.kind}+dedupe`
+        })
+      );
+    }
+    const taken = parsed.unwrap();
+    const envelopeId = taken.envelopeId;
+    if (envelopeId === void 0) return sink.capture(error, taken);
+    const before = await store.seen(envelopeId);
+    if (before !== void 0) return Result.ok({ deduplicated: true, id: before });
+    const receipt = await sink.capture(error, taken);
+    if (receipt.isErr()) return receipt;
+    await store.remember(envelopeId, receipt.unwrap().id);
+    return receipt;
+  },
+  flush: () => sink.flush(),
+  kind: `${sink.kind}+dedupe`
+});
+
+// src/last-event.ts
+var withLastEvent = (sink, record, now = Date.now) => ({
+  capture: async (error, attributes) => {
+    const receipt = await sink.capture(error, attributes);
+    if (receipt.isErr() || receipt.value.deduplicated) return receipt;
+    try {
+      await record({
+        at: now(),
+        id: receipt.value.id,
+        ...attributes.release === void 0 ? {} : { release: attributes.release },
+        sink: sink.kind
+      });
+    } catch {
+    }
+    return receipt;
+  },
+  flush: () => sink.flush(),
+  kind: sink.kind
+});
+
+// src/span.ts
+var SPAN_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)+$/;
+var isSpanName = (name) => SPAN_NAME.test(name);
+
+// src/tracer.ts
+var createMemoryTracer = (options = {}) => {
+  const now = options.now ?? (() => performance.now());
+  const spans = [];
+  return {
+    clear: () => {
+      spans.length = 0;
+    },
+    kind: "memory",
+    span: async (name, attributes, body) => {
+      const started = now();
+      const record = (outcome, error) => {
+        spans.push({
+          attributes,
+          conventional: isSpanName(name),
+          durationMs: now() - started,
+          ...error === void 0 ? {} : { error },
+          name,
+          outcome
+        });
+      };
+      try {
+        const value = await body();
+        record("ok");
+        return value;
+      } catch (thrown) {
+        record("error", thrown instanceof Error ? thrown : new Error(String(thrown)));
+        throw thrown;
+      }
+    },
+    get spans() {
+      return spans;
+    }
+  };
+};
+var spanAttributesAreValid = (span) => parseAttributes(span.attributes).isOk();
+export {
+  ATTRIBUTE_KEYS,
+  InvalidAttributes,
+  PROBE_SERVICE,
+  SPAN_NAME_CONVENTION,
+  SinkFailure,
+  attributesSchema,
+  createMemorySink,
+  createMemoryTracer,
+  createSwallowingSink,
+  exitCodeOf,
+  formatProof,
+  idFor,
+  isSpanName,
+  isUuid,
+  memoryProbe,
+  parseAttributes,
+  proveObservability,
+  randomUuid,
+  spanAttributesAreValid,
+  uuidForEnvelope,
+  uuidFrom,
+  withDedupe,
+  withLastEvent
+};

package/dist/observability-cli.js

@@ -0,0 +1,229 @@
+import {
+  exitCodeOf,
+  formatProof,
+  memoryProbe,
+  proveObservability
+} from "./chunk-UFR2R2VM.js";
+import {
+  createPostHogSink
+} from "./chunk-EJS3A3ZV.js";
+import "./chunk-2ZTQU3OO.js";
+
+// src/observability-cli.ts
+import { spawnSync } from "child_process";
+
+// src/posthog/stub.ts
+import { createServer } from "http";
+import { gunzipSync } from "zlib";
+var bodyOf = (chunks, encoding) => {
+  const raw = Buffer.concat(chunks);
+  return encoding === "gzip" ? gunzipSync(raw).toString("utf8") : raw.toString("utf8");
+};
+var eventsIn = (text) => {
+  const parsed = JSON.parse(text);
+  return parsed.batch ?? [];
+};
+var listening = (server) => new Promise((resolve, reject) => {
+  server.once("error", reject);
+  server.listen(0, "127.0.0.1", () => {
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      reject(new Error("the stub server did not take a port"));
+      return;
+    }
+    resolve(address.port);
+  });
+});
+var startPostHogStub = async ({
+  status = 200
+} = {}) => {
+  const events = [];
+  let requests = 0;
+  const server = createServer((request, response) => {
+    const chunks = [];
+    request.on("data", (chunk) => chunks.push(chunk));
+    request.on("end", () => {
+      requests += 1;
+      try {
+        events.push(...eventsIn(bodyOf(chunks, request.headers["content-encoding"])));
+      } catch {
+      }
+      response.writeHead(status, { "content-type": "application/json" });
+      response.end(status === 200 ? '{"status":"Ok"}' : '{"error":"refused"}');
+    });
+  });
+  const port = await listening(server);
+  return {
+    close: () => new Promise((resolve) => {
+      server.closeAllConnections();
+      server.close(() => resolve());
+    }),
+    get events() {
+      return events;
+    },
+    get requests() {
+      return requests;
+    },
+    url: `http://127.0.0.1:${port}`
+  };
+};
+
+// src/observability-cli.ts
+var USAGE = `geonosis-observability prove --sink <memory|posthog-stub|posthog> [--timeout <seconds>] [--verify-command <cmd>]
+
+Plants an error with a trace id nothing else in the world has, and then goes and LOOKS for it. A
+sink answers ok whether or not it kept anything \u2014 during.day's no-key sink answers ok in production
+\u2014 so a gate over one is green for ever unless something reads the sink back.
+
+  memory        The in-process buffer. Proves the port, the vocabulary and the dedupe, and nothing
+                about a network.
+
+  posthog-stub  The REAL posthog-node against a stub ingest endpoint this command starts on
+                loopback. Proves the adapter, the gzip, the batch and the uuid that carries the
+                dedupe \u2014 with no key and no internet.
+
+  posthog       The real vendor, from POSTHOG_API_KEY and POSTHOG_HOST. Sending is not arriving, so
+                the read-back is --verify-command: it runs with GEONOSIS_TRACE_ID in its environment
+                and must exit 0 when it can see the trace id in your project. Without one this
+                refuses, because "the SDK did not complain" is not evidence.
+
+Verdicts, and the exit code each carries:
+
+  PROVEN         0   the planted error was found, named by its trace id
+  CANNOT FAIL    2   the sink answered ok and kept nothing
+  MISREAD        2   the sink kept something, but not what was planted
+  CANNOT MEASURE 2   nothing was configured, or the plant never reached the sink at all`;
+var SINKS = ["memory", "posthog", "posthog-stub"];
+var VALUED = /* @__PURE__ */ new Set(["--sink", "--timeout", "--verify-command"]);
+var parseProveArgs = (argv) => {
+  const read = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index] ?? "";
+    const value = argv[index + 1];
+    if (!VALUED.has(flag)) throw new Error(`unknown argument "${flag}"`);
+    if (value === void 0 || value.startsWith("--")) throw new Error(`${flag} needs a value`);
+    read[flag] = value;
+    index += 1;
+  }
+  const sink = read["--sink"];
+  if (sink === void 0) throw new Error(`--sink is required \u2014 one of ${SINKS.join(", ")}`);
+  if (!SINKS.includes(sink)) {
+    throw new Error(`unknown sink "${sink}" \u2014 one of ${SINKS.join(", ")}`);
+  }
+  const seconds = Number(read["--timeout"] ?? "10");
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new Error(`--timeout must be a positive number of seconds, not "${read["--timeout"]}"`);
+  }
+  return {
+    sink,
+    timeoutMs: seconds * 1e3,
+    ...read["--verify-command"] === void 0 ? {} : { verifyCommand: read["--verify-command"] }
+  };
+};
+var loadPostHog = async () => {
+  try {
+    const vendor = await import("posthog-node");
+    return vendor.PostHog;
+  } catch (cause) {
+    throw new Error(
+      `posthog-node is not installed here, so nothing can be proved against PostHog: ${cause.message}`,
+      { cause }
+    );
+  }
+};
+var posthogSink = async ({ apiKey, host }) => {
+  const PostHog = await loadPostHog();
+  return createPostHogSink({
+    newClient: (batchSize) => new PostHog(apiKey, {
+      disableGeoip: true,
+      // The probe's own answer must not be "it timed out retrying"; a refusal is the finding.
+      fetchRetryCount: 0,
+      flushAt: batchSize,
+      flushInterval: 0,
+      host
+    })
+  });
+};
+var stubProbe = async () => {
+  const stub = await startPostHogStub();
+  const sink = await posthogSink({ apiKey: "phc_geonosis_probe", host: stub.url });
+  return {
+    close: () => stub.close(),
+    kind: sink.kind,
+    seen: () => Promise.resolve(stub.events.map((one) => one.uuid).filter((one) => one !== void 0)),
+    sink
+  };
+};
+var vendorProbe = async ({
+  apiKey,
+  host,
+  verifyCommand
+}) => {
+  const sink = await posthogSink({ apiKey, host });
+  return {
+    kind: sink.kind,
+    seen: (traceId) => Promise.resolve(seenByCommand(verifyCommand, traceId)),
+    sink
+  };
+};
+var seenByCommand = (command, traceId) => {
+  if (traceId === void 0) return [];
+  const done = spawnSync(command, {
+    encoding: "utf8",
+    env: { ...process.env, GEONOSIS_TRACE_ID: traceId },
+    shell: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return done.status === 0 ? [traceId] : [];
+};
+var probeFor = async (args) => {
+  if (args.sink === "memory") return memoryProbe();
+  if (args.sink === "posthog-stub") return stubProbe();
+  const apiKey = process.env.POSTHOG_API_KEY ?? "";
+  if (apiKey === "") return void 0;
+  const host = process.env.POSTHOG_HOST ?? "";
+  if (host === "") {
+    throw new Error(
+      "POSTHOG_API_KEY is set but POSTHOG_HOST is not \u2014 name the ingest host you mean rather than letting a probe pick one (eu.i.posthog.com and us.i.posthog.com are different projects)"
+    );
+  }
+  if (args.verifyCommand === void 0) {
+    throw new Error(
+      `a key is not a read-back: pass --verify-command <cmd>, which runs with GEONOSIS_TRACE_ID in its environment and must exit 0 when it can see that id in your project. Nothing in this kit queries ${host} on your behalf, and "the SDK did not complain" is the evidence this whole command exists because of`
+    );
+  }
+  return vendorProbe({ apiKey, host, verifyCommand: args.verifyCommand });
+};
+var proofFor = async (args) => {
+  try {
+    return await proveObservability({ probe: await probeFor(args), timeoutMs: args.timeoutMs });
+  } catch (cause) {
+    return { kind: args.sink, reason: cause.message, verdict: "cannot-measure" };
+  }
+};
+var main = async () => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}
+`);
+    return argv.length === 0 ? 2 : 0;
+  }
+  const [command, ...rest] = argv;
+  if (command !== "prove") {
+    throw new Error(`unknown command "${command}" \u2014 this bin has one, "prove". See --help.`);
+  }
+  const proof = await proofFor(parseProveArgs(rest));
+  process.stdout.write(`${formatProof(proof)}
+`);
+  return exitCodeOf(proof);
+};
+try {
+  process.exit(await main());
+} catch (error) {
+  process.stderr.write(`geonosis-observability: ${error.message}
+`);
+  process.exit(2);
+}
+export {
+  parseProveArgs
+};

package/dist/ports-Ct5eq-HS.d.ts

@@ -0,0 +1,116 @@
+import * as better_result from 'better-result';
+import { Result } from 'better-result';
+
+/**
+ * The ports.
+ *
+ * during.day's seam answers `Promise<number>` — `events.length` from the real sink, `0` from the
+ * one with no key, a rejected promise from a dead transport — and it is handed to `waitUntil`,
+ * where nothing reads it. A count cannot say *failed* and nobody was listening anyway. That is the
+ * shape `no-void-port` refuses, wearing a number instead of `void`.
+ *
+ * So the answer is a `Result` and it carries an ID. React strips an error's message on the way to a
+ * browser; a deploy renames every stack frame. The one thing that survives both is the id the sink
+ * filed the report under, which is why it is in the receipt rather than in a log line.
+ */
+/** A value a vendor can put on the wire without a serializer of its own. */
+type AttributeValue = boolean | null | number | string;
+/**
+ * The vocabulary. Every field is one of these or it goes in `extra`, and `extra` may not shadow one
+ * of these — a `service` in the bag and a `service` on the envelope is a report with two answers.
+ */
+type Attributes = {
+    /**
+     * The person or process that caused it, when there is one. This is the only field that MAY carry
+     * an identity; `tenant` may not.
+     */
+    actor?: string;
+    /**
+     * The id this occurrence already has upstream — a queue envelope, a job id, a request id. The
+     * dedupe key, and the id the sink files under when it is present.
+     */
+    envelopeId?: string;
+    /** Anything this vocabulary does not name. May not shadow a field it does. */
+    extra?: Record<string, AttributeValue>;
+    /**
+     * Which build. NEITHER consumer attaches one today, which is why a production error could not be
+     * pinned to a deploy — the first of the four lying instruments of `docs/rules-backlog.md` #42.
+     */
+    release?: string;
+    /** Where the code was running: `node`, `workerd`, `browser`, a container id. An open string. */
+    runtime?: string;
+    /** Which service emitted this. Required: a report nobody can route is a report nobody reads. */
+    service: string;
+    /**
+     * The tenant, ALWAYS a group id and never a person. It is the join key every dashboard fans out
+     * on and the field a GDPR erasure cannot reach once a person is in it.
+     */
+    tenant?: string;
+};
+/** What a sink answers with when it accepted a report. */
+type CaptureReceipt = {
+    /**
+     * True when the sink recognised this envelope id and did not file it a second time. A capture
+     * that did less than it looks like it did says so, rather than being counted as another send.
+     */
+    deduplicated: boolean;
+    /** The id the sink filed it under — what a human greps the vendor for. */
+    id: string;
+};
+declare const SinkFailure_base: better_result.TaggedErrorClass<"SinkFailure">;
+/**
+ * Why a sink could not take a report. A tagged error so a consumer can match it beside its own,
+ * and an `Error` so it still prints and still has a stack.
+ */
+declare class SinkFailure extends SinkFailure_base<{
+    cause?: unknown;
+    message: string;
+    /** Which sink. A failure that cannot name itself sends the reader to the wrong file. */
+    sink: string;
+}> {
+}
+type ErrorSink = {
+    capture: (error: Error, attributes: Attributes) => Promise<Result<CaptureReceipt, SinkFailure>>;
+    /**
+     * Send whatever is held. Explicit, always: there is no long-lived process to run a background
+     * timer in, and a timer left running is an isolate that will not shut down.
+     */
+    flush: () => Promise<Result<void, SinkFailure>>;
+    /** What this sink is, in a verdict. `memory`, `posthog`, `swallowing`, `memory+dedupe`. */
+    kind: string;
+};
+/** What a tracer recorded about one span. */
+type SpanRecord = {
+    attributes: Attributes;
+    /** Whether the name follows `SPAN_NAME_CONVENTION`. Recorded, never enforced by a throw. */
+    conventional: boolean;
+    durationMs: number;
+    error?: Error;
+    name: string;
+    outcome: 'error' | 'ok';
+};
+/**
+ * `span` returns whatever the body returned and rethrows whatever it threw. It is a recorder, not a
+ * gate: a tracer that swallowed a throw would make a failed request answer 200, which is the third
+ * lying instrument of #42 rebuilt on purpose. Its own failures are its own business and never the
+ * caller's — the same trade during.day's `reportFailure` makes out loud.
+ */
+type Tracer = {
+    kind: string;
+    span: <Value>(name: string, attributes: Attributes, body: () => Promise<Value>) => Promise<Value>;
+};
+/**
+ * The record a consumer writes somewhere `geonosis-doctor` can read it — a file on Node, a KV entry
+ * on workerd. The doctor parses this shape and never imports this package: a check that needed the
+ * library it checks is a check that cannot run where the library is missing, which is the case it
+ * exists to find.
+ */
+type LastEventRecord = {
+    /** Epoch milliseconds. */
+    at: number;
+    id: string;
+    release?: string;
+    sink: string;
+};
+
+export { type Attributes as A, type CaptureReceipt as C, type ErrorSink as E, type LastEventRecord as L, type SpanRecord as S, type Tracer as T, type AttributeValue as a, SinkFailure as b };