opencode-swarm 7.136.5 → 7.137.0

package/dist/observability/catalog.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The event catalog (issue #2029).
+ *
+ * Exactly 39 entries, matching the `TelemetryEvent` union at
+ * `src/telemetry.ts:15-86`. Thirty-eight of them predate this change; the 39th is
+ * `agent_conflict_detected`, which before this change was emitted in
+ * production through a force-cast past the type system before this change
+ * (at `src/hooks/conflict-resolution.ts:67-70` in the BASE tree; the replacement typed call is
+ * `:73` here) and was absent from the union. That
+ * 39th entry is the already-found instance of the defect class this contract
+ * exists to close: an event kind can enter the stream with no registration.
+ *
+ * Every entry names a real producer `file:line`, a retention owner issue at or
+ * above #2030 — every entry today cites the #2030-#2051 programme, but only the
+ * LOWER bound is enforced, so a successor issue numbered past that window is not
+ * forced into a false in-window citation — a privacy class, a doc anchor and a
+ * test file. An entry with no
+ * live reader declares `consumers: []` AND a `futureOwnerIssue` — an empty
+ * consumer list without an owner is a contract violation, not a shrug.
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+import type { EventCategory, EventSeverity, PrivacyClass, WorkflowIdKey } from './envelope.js';
+/** Which external attribute table, if any, an entry projects onto. */
+export type OtelMappingKind = 'genai' | 'openinference' | 'none';
+/** One catalogued event kind. */
+export interface CatalogEntry {
+    /** The wire value written as the `event` field. */
+    readonly kind: string;
+    readonly category: EventCategory;
+    readonly severity: EventSeverity;
+    readonly privacyClass: PrivacyClass;
+    /** Real `file:line` of the emit call that produces this kind. */
+    readonly producer: string;
+    /**
+     * Real `file:line` of each live reader. Empty is permitted ONLY together
+     * with {@link futureOwnerIssue}.
+     */
+    readonly consumers: readonly string[];
+    /** Owner issue for a kind that currently has no reader. */
+    readonly futureOwnerIssue?: number;
+    /**
+     * Owner issue for this kind's retention/lifecycle decision. Must be >= #2030;
+     * every entry today names the #2030-#2051 programme, but no upper bound is
+     * enforced (see `scripts/check-event-contract.ts`).
+     */
+    readonly retentionOwnerIssue: number;
+    /**
+     * Correlation IDs the producer GENUINELY always supplies. Conservative by
+     * construction: listing an ID the producer sometimes omits would turn a
+     * truthful "absent" into a false violation, and listing one nothing
+     * populates would make every event of that kind violate.
+     */
+    readonly requiredWorkflowIds: readonly WorkflowIdKey[];
+    /**
+     * Correlation IDs this producer genuinely never holds. Presence of one means
+     * an ID was manufactured somewhere upstream to make a join succeed — the
+     * exact anti-pattern issue #2029 item 2 forbids.
+     */
+    readonly forbiddenWorkflowIds: readonly WorkflowIdKey[];
+    /**
+     * Whether an event of this kind must carry `trace.parentSpanId`.
+     *
+     * `false` for all 39 entries today, and that is a truthful statement about
+     * the current system rather than a placeholder: no producer supplies a
+     * parent span, so `createObservation` never sets one. Setting this to `true`
+     * for a kind whose producer cannot supply a parent would make every
+     * production event of that kind violate.
+     */
+    readonly requiresParent: boolean;
+    /** Whether typed span links are meaningful for this kind. */
+    readonly allowsLinks: boolean;
+    readonly otelMapping: OtelMappingKind;
+    /** Anchor in `docs/observability-event-contract.md`. */
+    readonly docAnchor: string;
+    /** Test that asserts this entry's completeness. */
+    readonly testFile: string;
+}
+/** The catalog, keyed by wire event kind. */
+export declare const EVENT_CATALOG: Readonly<Record<string, CatalogEntry>>;
+/** Every catalogued kind, in declaration order. */
+export declare const CATALOG_KINDS: readonly string[];
+/** Own-property catalog lookup. Returns `undefined` for an unknown kind. */
+export declare function getCatalogEntry(kind: string): CatalogEntry | undefined;

package/dist/observability/envelope.d.ts

@@ -0,0 +1,401 @@
+/**
+ * Canonical observability event envelope (issue #2029).
+ *
+ * These zod schemas are the contract definition. They are used by tests and by
+ * the static contract check — NOT on the `emit()` hot path. `createObservation`
+ * constructs a plain object and never calls `.parse()`, because parsing would
+ * reallocate the envelope on every emit and, critically, would clone or reject
+ * `legacy.raw` (see {@link LegacyProjectionSchema}).
+ *
+ * Import rules: `zod` only. No filesystem, network, subprocess, or OTel SDK.
+ */
+import { z } from 'zod';
+/**
+ * Version of the envelope shape itself.
+ *
+ * Deliberately independent of the OTel GenAI / OpenInference mapping versions in
+ * `otel-mapping.ts`: external convention churn must never force a change to
+ * internal domain state (issue #2029 item 6).
+ */
+export declare const OBSERVABILITY_SCHEMA_VERSION = 1;
+/**
+ * Coarse event family. `unrecognized` is reserved for the runtime fail-open
+ * path: an event kind absent from `EVENT_CATALOG` is classified, never dropped.
+ */
+export declare const EventCategorySchema: z.ZodEnum<{
+    lifecycle: "lifecycle";
+    delegation: "delegation";
+    gate: "gate";
+    plan: "plan";
+    evidence: "evidence";
+    guardrail: "guardrail";
+    knowledge: "knowledge";
+    cost: "cost";
+    prm: "prm";
+    conflict: "conflict";
+    unrecognized: "unrecognized";
+}>;
+export type EventCategory = z.infer<typeof EventCategorySchema>;
+/** Syslog-shaped severity ladder. */
+export declare const EventSeveritySchema: z.ZodEnum<{
+    error: "error";
+    debug: "debug";
+    info: "info";
+    notice: "notice";
+    warning: "warning";
+    critical: "critical";
+}>;
+export type EventSeverity = z.infer<typeof EventSeveritySchema>;
+/**
+ * Handling class for the payload an event carries.
+ *
+ * - `operational`  — counters, enums, durations. No identifiers.
+ * - `pseudonymous` — session/task/agent identifiers, but no paths or free text.
+ * - `sensitive`    — filesystem paths or free-text error strings that can embed
+ *                    a path.
+ * - `content`      — prompts, responses, documents, tool payloads. No event in
+ *                    the current catalog is `content`; the class exists so a
+ *                    future producer cannot enter the stream unclassified.
+ */
+export declare const PrivacyClassSchema: z.ZodEnum<{
+    operational: "operational";
+    pseudonymous: "pseudonymous";
+    sensitive: "sensitive";
+    content: "content";
+}>;
+export type PrivacyClass = z.infer<typeof PrivacyClassSchema>;
+/**
+ * How much trust the recorded time deserves.
+ *
+ * - `exact`        — the producer supplied the instant the thing happened.
+ * - `writer-clock` — the time was read by the writer at record time (this is
+ *                    what every current producer does).
+ * - `inferred`     — reconstructed from surrounding records.
+ * - `unknown`      — no defensible statement can be made. NOT a synonym for
+ *                    `writer-clock` (issue #2029 item 4: unknown is not zero).
+ */
+export declare const TimingConfidenceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    exact: "exact";
+    "writer-clock": "writer-clock";
+    inferred: "inferred";
+}>;
+export type TimingConfidence = z.infer<typeof TimingConfidenceSchema>;
+/**
+ * A non-parent relationship to another span.
+ *
+ * `kind` records WHY the link exists, so a consumer can tell a resumed session
+ * apart from a parallel lane apart from a retry — a distinction the issue calls
+ * out as unrecoverable once flattened into an untyped parent pointer.
+ */
+export declare const SpanLinkSchema: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    kind: z.ZodEnum<{
+        resume: "resume";
+        lane: "lane";
+        "cross-process": "cross-process";
+        retry: "retry";
+        "parent-batch": "parent-batch";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SpanLink = z.infer<typeof SpanLinkSchema>;
+/** W3C-compatible trace context plus typed links. */
+export declare const TraceContextSchema: z.ZodObject<{
+    traceId: z.ZodString;
+    spanId: z.ZodString;
+    parentSpanId: z.ZodOptional<z.ZodString>;
+    links: z.ZodArray<z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodString;
+        kind: z.ZodEnum<{
+            resume: "resume";
+            lane: "lane";
+            "cross-process": "cross-process";
+            retry: "retry";
+            "parent-batch": "parent-batch";
+        }>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TraceContext = z.infer<typeof TraceContextSchema>;
+/**
+ * The correlation identifiers the contract recognizes.
+ *
+ * All optional by contract. An ID that the producer does not genuinely hold
+ * stays `undefined` — never `''`, never synthesized (issue #2029 item 2: never
+ * manufacture an ID to make a join succeed).
+ *
+ * The enumeration is exhaustive on purpose. A producer that needs a correlation
+ * axis not listed here must extend this schema and the catalog together, so a
+ * new join key cannot enter the stream unregistered.
+ */
+export declare const WorkflowIdsSchema: z.ZodObject<{
+    rootConversationId: z.ZodOptional<z.ZodString>;
+    hostSessionId: z.ZodOptional<z.ZodString>;
+    swarmSessionId: z.ZodOptional<z.ZodString>;
+    taskId: z.ZodOptional<z.ZodString>;
+    phaseId: z.ZodOptional<z.ZodString>;
+    laneId: z.ZodOptional<z.ZodString>;
+    batchId: z.ZodOptional<z.ZodString>;
+    resultId: z.ZodOptional<z.ZodString>;
+    councilRoundId: z.ZodOptional<z.ZodString>;
+    backgroundInvocationId: z.ZodOptional<z.ZodString>;
+    knowledgeTraceId: z.ZodOptional<z.ZodString>;
+    knowledgeEntryId: z.ZodOptional<z.ZodString>;
+    prRunId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkflowIds = z.infer<typeof WorkflowIdsSchema>;
+/** Key of a recognized correlation identifier. */
+export type WorkflowIdKey = keyof WorkflowIds;
+/**
+ * Pseudonymous lineage refs.
+ *
+ * Every field is a salted, truncated SHA-256 digest produced by
+ * `pseudonymousRef` — never a path, never a label. Absent means "the producer
+ * did not hold this", not "empty".
+ */
+export declare const LineageSchema: z.ZodObject<{
+    projectRef: z.ZodOptional<z.ZodString>;
+    cohortRef: z.ZodOptional<z.ZodString>;
+    worktreeRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Lineage = z.infer<typeof LineageSchema>;
+/**
+ * Environment facts about the writer.
+ *
+ * `gitSha` and `configHash` are deliberately left `undefined` by the current
+ * initialization path. This is a decision, not an oversight: obtaining a HEAD
+ * SHA would require a THIRD init-path subprocess (`ensureSwarmGitExcluded`
+ * already runs `git rev-parse --show-toplevel` and `git rev-parse --git-path
+ * info/exclude`, neither of which yields a SHA), and AGENTS.md invariant 1
+ * forbids adding unbounded Git work before the plugin manifest returns —
+ * "bounded is not free". See fix plan W2.
+ *
+ * Recording them as explicitly missing rather than as `''` or `'unknown'` is the
+ * issue's own item-4 rule ("unknown is not zero") applied to ourselves.
+ */
+export declare const ProvenanceSchema: z.ZodObject<{
+    pluginVersion: z.ZodOptional<z.ZodString>;
+    opencodeVersion: z.ZodOptional<z.ZodString>;
+    runtime: z.ZodOptional<z.ZodString>;
+    runtimeVersion: z.ZodOptional<z.ZodString>;
+    os: z.ZodOptional<z.ZodString>;
+    arch: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    configHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Provenance = z.infer<typeof ProvenanceSchema>;
+/**
+ * Terminal disposition, when the producer reported one.
+ *
+ * `status` absent means the producer said nothing about success or failure.
+ * `'unknown'` means the producer DID report a result the contract cannot map —
+ * a different fact, kept distinct on purpose.
+ */
+export declare const OutcomeSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        success: "success";
+        failure: "failure";
+        partial: "partial";
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+    errorName: z.ZodOptional<z.ZodString>;
+    errorMessage: z.ZodOptional<z.ZodString>;
+    retryIndex: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type Outcome = z.infer<typeof OutcomeSchema>;
+/**
+ * Sampling and privacy policy stamped on the event.
+ *
+ * `sampled: false` plus a `dropReason` is how a drop is made observable. A
+ * silently discarded event is exactly the failure the issue names.
+ */
+export declare const PolicySchema: z.ZodObject<{
+    sampled: z.ZodBoolean;
+    sampleRate: z.ZodNumber;
+    dropReason: z.ZodOptional<z.ZodString>;
+    privacyClass: z.ZodEnum<{
+        operational: "operational";
+        pseudonymous: "pseudonymous";
+        sensitive: "sensitive";
+        content: "content";
+    }>;
+}, z.core.$strip>;
+export type Policy = z.infer<typeof PolicySchema>;
+/**
+ * What the legacy adapter could establish about a pre-contract record.
+ *
+ * ## `raw` is an ALIAS, not a copy
+ *
+ * `raw` holds a REFERENCE to the caller's payload object. It is never cloned,
+ * never `JSON.stringify`-ed, never deep-traversed, and never passed through
+ * `.parse()`. Three properties depend on that:
+ *
+ *   1. **Key order** — the legacy JSONL line spreads the caller's object last,
+ *      so caller key order is preserved byte-for-byte.
+ *   2. **Key collisions** — a caller that supplies its own `timestamp` (see
+ *      `src/hooks/conflict-resolution.ts:55-66`) must keep winning on value.
+ *   3. **`undefined` elision** — `JSON.stringify` drops `undefined`-valued keys.
+ *      Any clone or parse step would change which keys survive.
+ *
+ * It is also a hard safety requirement: `src/telemetry.test.ts:137-162` emits
+ * circular objects, functions, `Symbol`s and `BigInt`s and asserts `emit()` does
+ * not throw. Cloning or serializing `raw` would throw on those payloads.
+ *
+ * ## `sourceSchemaVersion: null`
+ *
+ * `null` means "this store does not version its records — the version is
+ * UNKNOWN". It does NOT mean version zero. `.swarm/telemetry.jsonl` carries no
+ * version field at all; that absence is itself a finding of issue #2029, and
+ * recording it as `0` would fabricate a fact the store never stated.
+ */
+export declare const LegacyProjectionSchema: z.ZodObject<{
+    sourceStore: z.ZodString;
+    sourceSchemaVersion: z.ZodNullable<z.ZodNumber>;
+    timingConfidence: z.ZodEnum<{
+        unknown: "unknown";
+        exact: "exact";
+        "writer-clock": "writer-clock";
+        inferred: "inferred";
+    }>;
+    unknown: z.ZodArray<z.ZodString>;
+    extra: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    raw: z.ZodUnknown;
+}, z.core.$strip>;
+/**
+ * `raw` is required on every projection. zod infers a key typed `unknown` as
+ * optional (because `undefined extends unknown`), so the required-ness is
+ * restated here rather than weakened in the schema.
+ */
+export type LegacyProjection = Omit<z.infer<typeof LegacyProjectionSchema>, 'raw' | 'unknown' | 'extra'> & {
+    raw: unknown;
+    readonly unknown: readonly string[];
+    readonly extra: Readonly<Record<string, unknown>>;
+};
+/** The canonical observability event. */
+export declare const ObservabilityEventSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    eventId: z.ZodString;
+    kind: z.ZodString;
+    category: z.ZodEnum<{
+        lifecycle: "lifecycle";
+        delegation: "delegation";
+        gate: "gate";
+        plan: "plan";
+        evidence: "evidence";
+        guardrail: "guardrail";
+        knowledge: "knowledge";
+        cost: "cost";
+        prm: "prm";
+        conflict: "conflict";
+        unrecognized: "unrecognized";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        notice: "notice";
+        warning: "warning";
+        critical: "critical";
+    }>;
+    occurredAt: z.ZodString;
+    observedAt: z.ZodString;
+    writerSequence: z.ZodNumber;
+    trace: z.ZodObject<{
+        traceId: z.ZodString;
+        spanId: z.ZodString;
+        parentSpanId: z.ZodOptional<z.ZodString>;
+        links: z.ZodArray<z.ZodObject<{
+            traceId: z.ZodString;
+            spanId: z.ZodString;
+            kind: z.ZodEnum<{
+                resume: "resume";
+                lane: "lane";
+                "cross-process": "cross-process";
+                retry: "retry";
+                "parent-batch": "parent-batch";
+            }>;
+            note: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    workflow: z.ZodObject<{
+        rootConversationId: z.ZodOptional<z.ZodString>;
+        hostSessionId: z.ZodOptional<z.ZodString>;
+        swarmSessionId: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        phaseId: z.ZodOptional<z.ZodString>;
+        laneId: z.ZodOptional<z.ZodString>;
+        batchId: z.ZodOptional<z.ZodString>;
+        resultId: z.ZodOptional<z.ZodString>;
+        councilRoundId: z.ZodOptional<z.ZodString>;
+        backgroundInvocationId: z.ZodOptional<z.ZodString>;
+        knowledgeTraceId: z.ZodOptional<z.ZodString>;
+        knowledgeEntryId: z.ZodOptional<z.ZodString>;
+        prRunId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    lineage: z.ZodObject<{
+        projectRef: z.ZodOptional<z.ZodString>;
+        cohortRef: z.ZodOptional<z.ZodString>;
+        worktreeRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    provenance: z.ZodObject<{
+        pluginVersion: z.ZodOptional<z.ZodString>;
+        opencodeVersion: z.ZodOptional<z.ZodString>;
+        runtime: z.ZodOptional<z.ZodString>;
+        runtimeVersion: z.ZodOptional<z.ZodString>;
+        os: z.ZodOptional<z.ZodString>;
+        arch: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        configHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    outcome: z.ZodObject<{
+        status: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            success: "success";
+            failure: "failure";
+            partial: "partial";
+        }>>;
+        reason: z.ZodOptional<z.ZodString>;
+        errorName: z.ZodOptional<z.ZodString>;
+        errorMessage: z.ZodOptional<z.ZodString>;
+        retryIndex: z.ZodOptional<z.ZodNumber>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    policy: z.ZodObject<{
+        sampled: z.ZodBoolean;
+        sampleRate: z.ZodNumber;
+        dropReason: z.ZodOptional<z.ZodString>;
+        privacyClass: z.ZodEnum<{
+            operational: "operational";
+            pseudonymous: "pseudonymous";
+            sensitive: "sensitive";
+            content: "content";
+        }>;
+    }, z.core.$strip>;
+    legacy: z.ZodObject<{
+        sourceStore: z.ZodString;
+        sourceSchemaVersion: z.ZodNullable<z.ZodNumber>;
+        timingConfidence: z.ZodEnum<{
+            unknown: "unknown";
+            exact: "exact";
+            "writer-clock": "writer-clock";
+            inferred: "inferred";
+        }>;
+        unknown: z.ZodArray<z.ZodString>;
+        extra: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        raw: z.ZodUnknown;
+    }, z.core.$strip>;
+    relationshipViolations: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** See {@link LegacyProjection} for why `legacy` is restated. */
+export type ObservabilityEvent = Omit<z.infer<typeof ObservabilityEventSchema>, 'legacy'> & {
+    legacy: LegacyProjection;
+};

package/dist/observability/ids.d.ts

@@ -0,0 +1,97 @@
+/** Hex width of a W3C `trace-id`. */
+export declare const TRACE_ID_HEX_LENGTH: number;
+/** Hex width of a W3C span id. */
+export declare const SPAN_ID_HEX_LENGTH: number;
+/**
+ * Environment variable that overrides the lineage salt.
+ *
+ * Deliberately NOT read at module scope: reading `process.env` during module
+ * evaluation would make the salt depend on import order and would defeat any
+ * test that sets it after import. `resolveLineageSalt()` reads it per call.
+ */
+export declare const LINEAGE_SALT_ENV = "SWARM_OBSERVABILITY_LINEAGE_SALT";
+/**
+ * Salt used when {@link LINEAGE_SALT_ENV} is unset.
+ *
+ * A constant default is intentional: lineage refs must be stable for a given
+ * path across processes and restarts, otherwise `projectRef` could not correlate
+ * two runs of the same project. Operators who want cross-install unlinkability
+ * set {@link LINEAGE_SALT_ENV} to a private value.
+ */
+export declare const DEFAULT_LINEAGE_SALT = "opencode-swarm/observability/lineage/v1";
+/** Hex characters retained from the SHA-256 digest for a lineage ref. */
+export declare const PSEUDONYMOUS_REF_LENGTH = 16;
+/** A correlated `traceId` + `spanId` pair produced from one CSPRNG call. */
+export interface TraceAndSpanId {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+/**
+ * Generate a W3C-compatible trace id: 32 lowercase hex characters, never
+ * all-zero.
+ *
+ * NAME COLLISION, deliberate to record rather than rename: `newTraceId` in
+ * `src/hooks/knowledge-events.ts` has the identical `(): string` signature but
+ * a DIFFERENT on-wire shape — a 36-character RFC 4122 UUID, not 32 hex
+ * characters. Nothing outside this directory imports this one, and it is no
+ * longer re-exported from `src/observability/index.ts`, so the two cannot be
+ * confused through the barrel. (`newEventId` is unaffected: both return
+ * `randomUUID()`.)
+ */
+export declare function newTraceId(): string;
+/**
+ * Generate a W3C-compatible span id: 16 lowercase hex characters, never
+ * all-zero.
+ */
+export declare function newSpanId(): string;
+/** Generate an event id (RFC 4122 UUID v4). */
+export declare function newEventId(): string;
+/**
+ * Derive a correlated trace/span pair, consuming 24 bytes from the pool above.
+ *
+ * This exists for the hot path: `createObservation` runs on every `emit()`, and
+ * src/telemetry.ts:315-317 documents that path as deliberately frugal.
+ */
+export declare function newTraceAndSpanId(): TraceAndSpanId;
+/**
+ * Resolve the lineage salt.
+ *
+ * Reads {@link LINEAGE_SALT_ENV} at call time (never at module scope) and falls
+ * back to {@link DEFAULT_LINEAGE_SALT}. Reading an environment variable is not
+ * I/O — no file, socket, or subprocess is touched.
+ */
+export declare function resolveLineageSalt(): string;
+/**
+ * Produce a pseudonymous reference for an absolute path.
+ *
+ * `sha256(salt + NUL + absolutePath)`, truncated to 16 hex characters.
+ *
+ * Properties this guarantees, and why each matters (issue #2029 item 2 / AC3):
+ *   - The result never CONTAINS or ENCODES the input path. It is a one-way
+ *     digest, not an encoding.
+ *   - Two different project paths carrying the SAME cohort label produce
+ *     DIFFERENT refs, because the path is part of the digest input.
+ *   - The result is stable for a given (salt, path) pair, so the same project
+ *     correlates across processes and restarts.
+ *
+ * What it does NOT guarantee, stated plainly rather than overclaimed: this is a
+ * PSEUDONYM, not an anonymous value, and it is not "irreversible" in the sense
+ * that matters. With the PUBLIC {@link DEFAULT_LINEAGE_SALT} the digest input is
+ * fully known except for the path, and real paths are low entropy, so a holder
+ * of an export can CONFIRM a guessed path by re-hashing candidates and matching
+ * the ref. Setting {@link LINEAGE_SALT_ENV} to a private per-install value
+ * restores guess-resistance and makes refs unlinkable across installs. The
+ * algorithm is deliberately left alone here: deriving and persisting a
+ * per-install salt needs init-path I/O, which AGENTS.md invariant 1 forbids, so
+ * it belongs with #2047.
+ *
+ * SCOPE of the AC3 claim: `cohortRef` and `worktreeRef` are computed only when a
+ * caller supplies `cohortLabel` / `worktreeId` to `initObservability`. The sole
+ * production caller (`src/index.ts:732-744`) supplies neither, so both are
+ * `undefined` in every real run today; AC3 is asserted at unit level against
+ * this API, not against a production emission path.
+ *
+ * @param absolutePath - Value to pseudonymize. Never stored or echoed.
+ * @param salt - Salt from {@link resolveLineageSalt}.
+ */
+export declare function pseudonymousRef(absolutePath: string, salt: string): string;

package/dist/observability/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The observability event contract (issue #2029).
+ *
+ * Reference documentation: `docs/observability-event-contract.md`.
+ *
+ * ## What this module is
+ *
+ * A versioned, discriminated, catalogued envelope for every observability record
+ * this plugin produces, plus the adapter that projects the existing untyped
+ * telemetry payloads onto it. The defect class it closes: *a production
+ * telemetry record is written without a versioned, discriminated, catalogued
+ * envelope — so a consumer cannot determine producer, schema generation, or
+ * unknown-versus-absent, and a new event kind can enter the stream without any
+ * registration.*
+ *
+ * ## The guarantees callers can rely on
+ *
+ * - **Zero I/O.** No filesystem, network, subprocess, dynamic import, or
+ *   OpenTelemetry SDK anywhere in this directory. `node:crypto` and `zod` are
+ *   the only imports. That is what keeps `initObservability` safe on the plugin
+ *   init path (AGENTS.md invariant 1) and the bundle Node-ESM-portable
+ *   (invariant 2).
+ * - **`createObservation` never throws** — not on a circular object, a
+ *   function/`Symbol`/`BigInt` payload, an unknown kind, or `null` data. It
+ *   never serializes, clones, or deep-traverses the payload.
+ * - **`legacy.raw` is an ALIAS** to the caller's payload, never a copy. Key
+ *   order, key collisions and `undefined`-key elision in the written line depend
+ *   on it.
+ * - **Nothing is synthesized.** An identifier the producer does not hold stays
+ *   `undefined`; an unversioned store records `sourceSchemaVersion: null`
+ *   (unknown, not zero); an absent field is listed in `legacy.unknown` rather
+ *   than defaulted.
+ * - **Validation returns, never throws.** `validateEventRelationships` and
+ *   `assertBoundedCardinality` both yield verdicts.
+ *
+ * ## What it is NOT, stated plainly
+ *
+ * The envelope is not yet authoritative. `toLegacyTelemetryLine` is a
+ * deliberately lossy, legacy-pinned projection: the non-legacy fields
+ * (`eventId`, `trace`, `lineage`, `provenance`, `policy`, `writerSequence`,
+ * `relationshipViolations`) are currently discarded, and their consumer lands in
+ * **#2047**. Consequently `validateEventRelationships` does not bite at runtime
+ * today — it bites in unit tests and in the static contract check.
+ */
+export type { CatalogEntry, OtelMappingKind } from './catalog.js';
+export { CATALOG_KINDS, EVENT_CATALOG, getCatalogEntry, } from './catalog.js';
+export type { Lineage, ObservabilityEvent, Outcome, Policy, Provenance, } from './envelope.js';
+export { OBSERVABILITY_SCHEMA_VERSION, ObservabilityEventSchema, } from './envelope.js';
+export type { TraceAndSpanId } from './ids.js';
+export { newEventId, newSpanId, pseudonymousRef, SPAN_ID_HEX_LENGTH, TRACE_ID_HEX_LENGTH, } from './ids.js';
+export { adaptLegacyTelemetryPayload, extractOutcome, extractWorkflowIds, KNOWN_TELEMETRY_KEYS, LEGACY_ADAPTER_RULES, NON_OBJECT_PAYLOAD_MARKER, } from './legacy.js';
+export type { InitObservabilityInput } from './observe.js';
+export { createObservation, initObservability, resetObservabilityForTesting, toLegacyTelemetryLine, } from './observe.js';
+export { mappingForEntry, OPENINFERENCE_ATTRIBUTES, OPENINFERENCE_MAPPING_VERSION, OTEL_GENAI_ATTRIBUTES, OTEL_GENAI_MAPPING_VERSION, } from './otel-mapping.js';
+export type { RelationshipValidationResult } from './relationships.js';
+export { RELATIONSHIP_VIOLATION_CODES, validateEventRelationships, } from './relationships.js';
+export type { CardinalityResult } from './sampling.js';
+export { assertBoundedCardinality, METRIC_LABEL_ALLOWLIST, shouldSample, } from './sampling.js';