opencode-swarm 7.136.4 → 7.137.0

package/dist/memory/index.d.ts

@@ -12,7 +12,7 @@ export { invalidateMemoryStoreDirCache, isMemoryLinked, MEMORY_LINK_POINTER_FILE
 export { buildRecallPromptBlock } from './prompt-block';
 export type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter, } from './provider';
 export { buildMemoryRecallPlan, type MemoryRecallPlan, type MemoryRecallPlannerInput, } from './recall-planner';
-export { buildMemoryCohortFingerprintInput, computeMemoryCohortFingerprint, computeRedactionPolicyVersion, findSecrets, redactSecrets, } from './redaction';
+export { buildMemoryCohortFingerprintInput, computeMemoryCohortFingerprint, computeRedactionPolicyVersion, FINGERPRINT_ALGORITHM_VERSION, findSecrets, redactSecrets, } from './redaction';
 export { MEMORY_RECALL_PROFILES, type MemoryRecallProfile, normalizeMemoryAgentRole, resolveMemoryRecallProfile, } from './role-profiles';
 export { appendMemoryRunLog, sanitizeRunId } from './run-log';
 export { computeMemoryContentHash, createBundleId, createMemoryId, createProposalId, isExpired, normalizeMemoryText, validateCuratorMemoryDecision, validateMemoryProposal, validateMemoryRecordRules, } from './schema';

package/dist/memory/local-jsonl-provider.d.ts

@@ -55,7 +55,10 @@ export declare class LocalJsonlMemoryProvider implements MemoryProvider, MemoryP
     /**
      * #1850 (KC-001 fix): mirror the SQLite provider's fingerprint check. Reads
      * `memory-cohort-config.json` and throws on mismatch. Absent/malformed file
-     * is permissive (fail-open never strands memory).
+     * is permissive (fail-open never strands memory). #2062 F-012: a file whose
+     * `algorithm_version` is not the current one — or is present but
+     * uninterpretable — is also permissive, because the digests are not
+     * comparable; both warn with a re-link instruction.
      */
     private assertCohortConfigFingerprint;
     private activeMemory;

package/dist/memory/redaction.d.ts

@@ -20,6 +20,97 @@ export interface MemoryCohortFingerprintInput {
     embedding_dimension: number;
     embedding_version: string;
 }
+/**
+ * #2062 F-012: version of the cohort-fingerprint ALGORITHM (canonicalization +
+ * hash + truncation), persisted alongside the fingerprint in
+ * `memory-cohort-config.json` and read back by every consumer.
+ *
+ * Version 1 is the algorithm below (sorted-key canonical JSON -> sha256 -> first
+ * 12 hex chars). Files written before this field existed are treated as
+ * version 1, which is exactly correct: they were produced by this same
+ * algorithm, so they keep validating with no forced re-link.
+ *
+ * BUMP THIS whenever a change would alter the digest for an unchanged input —
+ * e.g. a different hash, a different truncation length, a change to
+ * `stableCanonicalStringify`'s output for a reachable input, or a change to the
+ * `MemoryCohortFingerprintInput` shape. Readers compare versions BEFORE
+ * comparing fingerprints, so a bump surfaces as "re-run `/swarm memory link`"
+ * instead of being misreported as a real provider/embedding config mismatch.
+ */
+export declare const FINGERPRINT_ALGORITHM_VERSION = 1;
+/**
+ * #2062 F-012 (R3 fix): the algorithm version implied by a persisted cohort
+ * config that has NO `algorithm_version` field. Every file written before the
+ * field existed was produced by algorithm version 1, so that is what an absent
+ * field means — permanently, whatever `FINGERPRINT_ALGORITHM_VERSION` later
+ * becomes.
+ *
+ * This MUST stay a standalone literal and must never be re-expressed in terms
+ * of `FINGERPRINT_ALGORITHM_VERSION`. If it tracked the current version, then
+ * the moment that constant is bumped every legacy file already on disk would
+ * report itself as current, the version gate could never fire for the very
+ * files it exists to protect, and a v1 digest would be byte-compared against a
+ * v2 expected value — which `SQLiteMemoryProvider` turns into a hard
+ * "config differs" throw. Defaulting to the current version is self-defeating
+ * at exactly the moment the mechanism is supposed to help.
+ *
+ * The explicit `: 1` literal type is the enforcement, not decoration — and it
+ * enforces only for as long as it is actually there. No runtime test can catch
+ * the aliasing refactor today (while `FINGERPRINT_ALGORITHM_VERSION` is still
+ * 1, an alias evaluates to 1 and every assertion passes), so the guard has to
+ * fire at the only moment the mistake becomes real: the bump.
+ *
+ * Both halves of that were measured against this repo with the constant
+ * temporarily set to 2, running `bunx tsc --noEmit`:
+ *
+ * - `LEGACY_…: 1 = FINGERPRINT_ALGORITHM_VERSION` (annotation KEPT)
+ *   -> exit 2, `TS2322: Type '2' is not assignable to type '1'`. Guard fires.
+ * - `LEGACY_… = FINGERPRINT_ALGORITHM_VERSION` (annotation DROPPED)
+ *   -> exit 0. Guard does NOT fire, and every legacy cohort file is stranded
+ *   silently.
+ *
+ * The second form is the one a refactorer actually types, so do NOT rely on
+ * `tsc` to catch removal of this annotation — the annotation is the thing
+ * being protected, not merely the mechanism. A legitimate bump that leaves
+ * this literal alone typechecks cleanly.
+ */
+export declare const LEGACY_FINGERPRINT_ALGORITHM_VERSION: 1;
+/**
+ * DI seam for testability (repo convention, cf. `src/utils/logger.ts`). Lets a
+ * test simulate a FUTURE bump of `FINGERPRINT_ALGORITHM_VERSION` without
+ * hand-editing the constant — the only way to exercise the legacy-file version
+ * gate before a real bump ever happens. Production code never mutates this.
+ */
+export declare const _internals: {
+    currentAlgorithmVersion: number;
+};
+/**
+ * Result of interpreting a persisted `algorithm_version` field:
+ * - `comparable` — stored digest was produced by the current algorithm, so a
+ *   byte comparison is meaningful.
+ * - `mismatch` — a known but different algorithm produced it; the digests are
+ *   not comparable, so callers skip the compare and fail OPEN with a re-link
+ *   instruction rather than reporting a config difference that does not exist.
+ * - `unknown` — the field is present but not a finite number, so the digest
+ *   cannot be attributed to any algorithm. Callers skip the compare too, but
+ *   must NOT assume it is current (that would byte-compare on a guess).
+ */
+export type StoredFingerprintAlgorithmVersion = {
+    status: 'comparable';
+} | {
+    status: 'mismatch';
+    storedVersion: number;
+    currentVersion: number;
+} | {
+    status: 'unknown';
+};
+/**
+ * Single source of truth for the version gate shared by all four readers
+ * (SQLite provider, local-jsonl provider, status service, knowledge
+ * diagnostics). Keeping it here means a future bump changes one file, and the
+ * absent-field semantics cannot silently drift apart across call sites.
+ */
+export declare function classifyStoredFingerprintAlgorithmVersion(rawStoredVersion: unknown, currentVersion?: number): StoredFingerprintAlgorithmVersion;
 export declare function computeMemoryCohortFingerprint(input: MemoryCohortFingerprintInput): string;
 /** Convenience: build the fingerprint input from a memory config subset. */
 export declare function buildMemoryCohortFingerprintInput(config: {

package/dist/memory/sqlite-provider.d.ts

@@ -148,7 +148,11 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
      * with this worktree's config (acceptance #10). Absent file = first link
      * (permissive — the linker writes it immediately after migration). A
      * malformed file is also permissive (fail-open never strands memory, but
-     * a mismatch is a hard error).
+     * a mismatch is a hard error). #2062 F-012: a file whose `algorithm_version`
+     * is not the current one — or is present but uninterpretable — is permissive
+     * too, because cross-algorithm digests are not comparable. Both warn with a
+     * re-link instruction rather than reporting a config mismatch that does not
+     * exist.
      */
     private assertCohortConfigFingerprint;
     private writeMemoryFts;

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;
+};