opencode-swarm 7.136.5 → 7.137.0

package/dist/observability/legacy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Legacy telemetry adapter (issue #2029 item 4 / AC2).
+ *
+ * Its real production input is the untyped `data: Record<string, unknown>` that
+ * `src/telemetry.ts:emit()` receives from 40+ call sites: caller-ordered,
+ * unversioned, with extra and missing fields. That is legacy-shaped input by
+ * definition, and adapting it is this module's genuine job.
+ *
+ * Two hard constraints govern every function here:
+ *   1. **Never throw.** `emit()` documents a never-throw guarantee
+ *      (`src/telemetry.ts:266,294`) and `src/telemetry.test.ts:137-162`
+ *      exercises circular objects, functions, `Symbol`s and `BigInt`s.
+ *   2. **Never deep-traverse, clone, or serialize the payload.** Only
+ *      `Object.keys` (shallow) and own-key reads. See `LegacyProjectionSchema`
+ *      for why `raw` must stay an alias.
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+import type { LegacyProjection, Outcome, WorkflowIds } from './envelope.js';
+/** The store these payloads are written to. */
+export declare const LEGACY_TELEMETRY_SOURCE_STORE = ".swarm/telemetry.jsonl";
+/** Marker recorded in `legacy.unknown` when the payload is not an object. */
+export declare const NON_OBJECT_PAYLOAD_MARKER = "<non-object-payload>";
+/**
+ * Marker recorded when the payload resisted shallow introspection — a Proxy
+ * whose `ownKeys` trap throws, or a throwing getter. The payload is still kept
+ * by reference; only our description of it is degraded.
+ */
+export declare const INTROSPECTION_FAILED_MARKER = "<payload-introspection-failed>";
+/**
+ * The adapter rules, stated as a checkable list.
+ *
+ * These are the item-4 rules of issue #2029. They are exported as data (not
+ * prose in a doc file) so the static contract check and the unit tests can
+ * assert against the same statement of intent the implementation follows.
+ */
+export declare const LEGACY_ADAPTER_RULES: readonly string[];
+/**
+ * Payload keys each producer is known to emit.
+ *
+ * Derived from the emit call sites in source, NOT from captured output: a key
+ * whose value is `undefined` is elided by `JSON.stringify`, so a captured line
+ * under-reports the producer's key set. Listing those keys here is precisely
+ * what makes `legacy.unknown` non-vacuous — `delegation_end` naming `model`,
+ * `gate` and `retry_index` lets the adapter say "the producer did not know
+ * these" instead of silently omitting them.
+ */
+export declare const KNOWN_TELEMETRY_KEYS: Readonly<Record<string, readonly string[]>>;
+export declare function adaptLegacyTelemetryPayload(kind: string, data: unknown, knownKeys: readonly string[]): LegacyProjection;
+/**
+ * Extract recognized correlation IDs from a legacy payload.
+ *
+ * Shallow, never throws, and NEVER synthesizes: an ID that is absent, empty, or
+ * of the wrong type stays `undefined`. Only the mappings a producer actually
+ * populates are implemented — `sessionId` to `hostSessionId`, `taskId`, `phase`
+ * to `phaseId`, `laneId`, `batchId`. The remaining eight recognized IDs have no
+ * current producer, and inventing an extraction for them would manufacture
+ * exactly the joins issue #2029 item 2 forbids.
+ */
+export declare function extractWorkflowIds(data: unknown): WorkflowIds;
+/**
+ * Extract terminal disposition from a legacy payload.
+ *
+ * Shallow and never throws. `durationMs` is deliberately never populated: no
+ * current producer reports a duration, and deriving one would fabricate a
+ * measurement.
+ */
+export declare function extractOutcome(data: unknown): Outcome;

package/dist/observability/observe.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Observation construction and the legacy line projection (issue #2029).
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK. Everything here
+ * is synchronous and allocation-only.
+ *
+ * ## Module state
+ *
+ * Four process-scoped variables. None is session-keyed, so AGENTS.md invariant 8
+ * (session-scoped state must be keyed by `sessionID` and bounded) does not
+ * apply: `_provenance` and `_lineage` are single small frozen-by-convention
+ * records describing THIS process, `_sampleRate` is a scalar, and
+ * `_writerSequence` is a scalar counter. None of them grows with session count,
+ * so there is nothing to evict. All four have a reset seam
+ * ({@link resetObservabilityForTesting}) so no test's assertions become order
+ * dependent.
+ */
+import { type ObservabilityEvent, type Provenance } from './envelope.js';
+/** Violation code stamped on a fallback event. */
+export declare const OBSERVATION_BUILD_FAILED = "observation_build_failed";
+/** Input to {@link initObservability}. */
+export interface InitObservabilityInput {
+    /** Absolute project root. Pseudonymized, never stored. */
+    directory?: string;
+    /** Cohort label (e.g. a swarm id). Pseudonymized together with `directory`. */
+    cohortLabel?: string;
+    /** Worktree identity. Pseudonymized, never stored. */
+    worktreeId?: string;
+    provenance?: Provenance;
+    sampleRate?: number;
+}
+/**
+ * Install process provenance and lineage.
+ *
+ * Performs ZERO I/O — it hashes strings the caller already holds. That matters
+ * for AGENTS.md invariant 1: this runs on the plugin init path, and init-path
+ * work must be fast, bounded and side-effect-minimal.
+ *
+ * Lineage refs are computed ONCE here and reused by every subsequent
+ * observation. Computing them per-emit would put three SHA-256 digests on the
+ * hot path for values that never change within a process.
+ *
+ * NEVER THROWS. The whole body is guarded: a failure here must not prevent the
+ * plugin manifest from being returned (invariant 1, fail-open).
+ */
+export declare function initObservability(input: InitObservabilityInput): void;
+/**
+ * Build the canonical observation for one emit.
+ *
+ * **NEVER THROWS.** Not on a circular object, not on a function / `Symbol` /
+ * `BigInt` payload, not on an unknown kind, not on `null` or `undefined` data.
+ * It never calls `JSON.stringify`, never clones, and never deep-traverses
+ * `data` — `src/telemetry.test.ts:137-162` emits exactly those payloads and
+ * asserts `emit()` does not throw, and `src/telemetry.ts:266` documents the
+ * never-throw guarantee. If anything inside fails, a minimal valid event is
+ * returned carrying `relationshipViolations: ['observation_build_failed']`.
+ *
+ * An UNCATALOGUED kind is classified (`category: 'unrecognized'`), never
+ * dropped. Preventing new unrecognized kinds is the static contract check's job,
+ * not a runtime drop.
+ *
+ * `occurredAt` is set equal to `observedAt`. That is a recorded finding, not an
+ * invention: no current producer supplies a distinct time at which the described
+ * thing happened, so claiming one would fabricate precision the source does not
+ * have.
+ */
+export declare function createObservation(kind: string, data: unknown): ObservabilityEvent;
+/**
+ * Project a canonical event onto the legacy `.swarm/telemetry.jsonl` record.
+ *
+ * ## This projection is LOSSY and LEGACY-PINNED
+ *
+ * The envelope's non-legacy fields — `eventId`, `trace` (`traceId`, `spanId`,
+ * `parentSpanId`, `links`), `lineage`, `provenance`, `policy`, `writerSequence`,
+ * `schemaVersion` and `relationshipViolations` — are **currently DISCARDED**.
+ * Nothing in this change consumes them; their consumer lands in **#2047**. That
+ * is stated here rather than buried: a reader of this function must not conclude
+ * the written line is the canonical record. It is not.
+ *
+ * ## Byte-for-byte preservation
+ *
+ * The caller's object is spread **LAST**, exactly as the pre-change inline line
+ * construction in `src/telemetry.ts` `emit()` did. Three properties depend on
+ * that ordering, and all three are observable in
+ * `tests/fixtures/observability/telemetry-lines-golden.json` (issue #2029 item
+ * 5 arm (a) — "preserve the existing output"):
+ *
+ *   1. **Caller key order** is preserved after `timestamp` and `event`.
+ *   2. **Caller key collisions win on value.** `conflict-resolution.ts:55-66`
+ *      supplies its own `timestamp` and `type`; the caller's `timestamp` value
+ *      overwrites the envelope's while the key keeps position 1.
+ *   3. **`undefined`-key elision** is unchanged, because the caller's own object
+ *      is spread rather than a reconstruction of it.
+ *
+ * `timestamp` is taken from `event.observedAt` — a real, load-bearing data
+ * dependency on the canonical event, which is why this composition is not the
+ * identity function on the emit path.
+ *
+ * A non-object, `null`, or array payload yields just `{ timestamp, event }`,
+ * matching what `JSON.stringify({ timestamp, event, ...data })` produces for
+ * those inputs.
+ */
+export declare function toLegacyTelemetryLine(event: ObservabilityEvent): Record<string, unknown>;
+/**
+ * Reset all four module-scoped variables.
+ *
+ * Called alongside `resetTelemetryForTesting` so no test's assertions become
+ * dependent on how many events an earlier test emitted.
+ *
+ * @internal - For testing only
+ */
+export declare function resetObservabilityForTesting(): void;

package/dist/observability/otel-mapping.d.ts

@@ -0,0 +1,48 @@
+/**
+ * External-convention attribute mappings (issue #2029 item 6).
+ *
+ * These are INERT LOOKUP TABLES. There is no OpenTelemetry SDK dependency, no
+ * exporter, and no runtime consumer in this change: the tables are consumed as
+ * data by the static contract check (which asserts every catalog entry records a
+ * mapping decision) and by `docs/observability-event-contract.md`. The runtime
+ * consumer lands in #2049.
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+import type { OtelMappingKind } from './catalog.js';
+/**
+ * OpenTelemetry semantic-convention generation these GenAI attribute names track.
+ *
+ * Pinned SEPARATELY from `OBSERVABILITY_SCHEMA_VERSION`. That separation is the
+ * whole point of issue #2029 item 6: the GenAI conventions are an external,
+ * still-unstable vocabulary. If they were versioned together, an upstream rename
+ * would force a bump of the internal envelope version and every consumer would
+ * be told the domain shape changed when nothing about the domain changed.
+ * External convention churn must never change internal domain state.
+ */
+export declare const OTEL_GENAI_MAPPING_VERSION = "1.29.0";
+/**
+ * OpenInference specification generation these attribute names track. Pinned
+ * separately from both {@link OTEL_GENAI_MAPPING_VERSION} and
+ * `OBSERVABILITY_SCHEMA_VERSION`, for the same reason.
+ */
+export declare const OPENINFERENCE_MAPPING_VERSION = "0.1.14";
+/**
+ * Internal envelope path to OTel GenAI attribute name.
+ *
+ * Keys are dotted paths into `ObservabilityEvent`. `legacy.raw.*` paths reach
+ * into the aliased producer payload, which is where token counts and the
+ * resolved model live today.
+ */
+export declare const OTEL_GENAI_ATTRIBUTES: Readonly<Record<string, string>>;
+/** Internal envelope path to OpenInference attribute name. */
+export declare const OPENINFERENCE_ATTRIBUTES: Readonly<Record<string, string>>;
+/**
+ * Resolve the attribute table a catalog entry projects onto.
+ *
+ * `'none'` is a real, recorded decision — "this kind has no external
+ * equivalent" — not a missing value. It returns an empty table, never
+ * `undefined`, so a consumer never has to distinguish "no mapping" from "not
+ * asked".
+ */
+export declare function mappingForEntry(mapping: OtelMappingKind): Readonly<Record<string, string>>;

package/dist/observability/relationships.d.ts

@@ -0,0 +1,44 @@
+import type { ObservabilityEvent } from './envelope.js';
+/** Verdict from {@link validateEventRelationships}. */
+export type RelationshipValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    violations: string[];
+};
+/**
+ * Stable violation codes.
+ *
+ * Codes are machine-readable and must not be renamed once emitted — they are the
+ * join key a downstream consumer will group on. The suffix after `:` is the
+ * offending identifier or link index.
+ */
+export declare const RELATIONSHIP_VIOLATION_CODES: Readonly<{
+    unknownKind: "unknown_kind";
+    requiredWorkflowIdMissing: "required_workflow_id_missing";
+    forbiddenWorkflowIdPresent: "forbidden_workflow_id_present";
+    parentSpanNotAllowed: "parent_span_not_allowed";
+    parentSpanMissing: "parent_span_missing";
+    malformedParentSpanId: "malformed_parent_span_id";
+    linksNotAllowed: "links_not_allowed";
+    malformedLinkTraceId: "malformed_link_trace_id";
+    malformedLinkSpanId: "malformed_link_span_id";
+    validationFailed: "relationship_validation_failed";
+}>;
+/**
+ * Validate an event against its catalogued relationship rules.
+ *
+ * Checks, in order:
+ *   (a) the kind is catalogued;
+ *   (b) every `requiredWorkflowIds` entry is present;
+ *   (c) no `forbiddenWorkflowIds` entry is present (a present one means an ID
+ *       was manufactured upstream — issue #2029 item 2);
+ *   (d) a parent span is absent when the kind does not take one;
+ *   (e) a parent span is present when the kind requires one;
+ *   (f) a present parent span is a well-formed W3C span id;
+ *   (g) links are absent when the kind does not allow them;
+ *   (h) every link carries a well-formed trace/span id pair.
+ *
+ * @returns `{ ok: true }` or `{ ok: false, violations }`. Never throws.
+ */
+export declare function validateEventRelationships(event: ObservabilityEvent): RelationshipValidationResult;

package/dist/observability/sampling.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Sampling and metric-cardinality policy (issue #2029).
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+/**
+ * Default sample rate.
+ *
+ * `1` = sample everything. This PR introduces no dropping: a drop that no
+ * consumer can see is exactly the silent data loss the issue names, and the
+ * consumer that would make a drop observable lands in #2047.
+ */
+export declare const DEFAULT_SAMPLE_RATE = 1;
+/**
+ * Decide whether a trace is sampled.
+ *
+ * **Deterministic by construction.** The decision is a pure function of the
+ * trace id and the rate: the LAST 8 hex characters of the trace id are read as
+ * an unsigned integer and compared against `rate * 0xffffffff`. The same trace
+ * therefore samples identically in every process, on every host, and across
+ * restarts — no shared state, no RNG, no coordination. That is what makes a
+ * sampled distributed trace complete rather than a set of disconnected
+ * fragments, and it is why the decision is not `Math.random()`.
+ *
+ * **CAVEAT — that property is currently VACUOUS in this system, and saying so
+ * is the point.** `createObservation` mints a FRESH `traceId` per event, with
+ * `links: []` and no `parentSpanId`, so every event today is its own
+ * single-span trace. At a rate below 1 the decision is therefore independent
+ * PER EVENT, not per logical trace: a "trace" never spans two events, so
+ * nothing can be kept whole or torn apart. Trace continuation — propagating one
+ * trace id across the events that belong together — is #2047's work, and only
+ * then does trace-coherent sampling become a real property rather than a
+ * latent one. Nothing is dropped today regardless: {@link DEFAULT_SAMPLE_RATE}
+ * is `1`.
+ *
+ * **Fail-open.** Every unusable input returns `true`. Dropping an event because
+ * an id was malformed would lose data silently, which is the failure mode this
+ * contract exists to prevent. A non-finite rate also fails open, for the same
+ * reason: `NaN` would otherwise fall through both bounds and make every
+ * comparison `false`, silently dropping everything.
+ *
+ * @param traceId - 32 lowercase hex characters.
+ * @param rate - `>= 1` samples everything, `<= 0` samples nothing.
+ */
+export declare function shouldSample(traceId: string, rate: number): boolean;
+/**
+ * The only labels permitted on a metric.
+ *
+ * Every member is bounded: a small, enumerable set of values that cannot grow
+ * with traffic. The rule this enforces, from issue #2029: **IDs, paths, users,
+ * tasks, and repositories belong in traces and logs, not metric labels.** A
+ * single unbounded label multiplies the time-series count by its cardinality and
+ * takes a metrics backend down; the trace already carries that detail, keyed to
+ * the same event.
+ */
+export declare const METRIC_LABEL_ALLOWLIST: readonly string[];
+/** Verdict from {@link assertBoundedCardinality}. */
+export type CardinalityResult = {
+    ok: true;
+} | {
+    ok: false;
+    violations: string[];
+};
+/** Stable violation codes, suffixed with the offending label. */
+export declare const CARDINALITY_VIOLATION_CODES: Readonly<{
+    notAllowlisted: "label_not_allowlisted";
+    highCardinalityShape: "high_cardinality_label_shape";
+}>;
+/**
+ * Check a metric's label set against the allowlist and against high-cardinality
+ * shapes.
+ *
+ * RETURNS a verdict; never throws. A label can produce both codes — the shape
+ * check runs independently of the allowlist check so that a newly-allowlisted
+ * label with an unbounded shape is still reported.
+ */
+export declare function assertBoundedCardinality(labels: readonly string[]): CardinalityResult;

package/dist/summaries/schema.d.ts

@@ -95,10 +95,10 @@ export declare const PhaseArchitectureSummarySchema: z.ZodObject<{
 export type PhaseArchitectureSummary = z.infer<typeof PhaseArchitectureSummarySchema>;
 export declare const SupervisorFindingSchema: z.ZodObject<{
     severity: z.ZodEnum<{
+        critical: "critical";
         low: "low";
         medium: "medium";
         high: "high";
-        critical: "critical";
     }>;
     category: z.ZodString;
     agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -135,10 +135,10 @@ export declare const ArchitectureSupervisorReportSchema: z.ZodObject<{
     }>;
     findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
         severity: z.ZodEnum<{
+            critical: "critical";
             low: "low";
             medium: "medium";
             high: "high";
-            critical: "critical";
         }>;
         category: z.ZodString;
         agents: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/telemetry.d.ts

@@ -1,3 +1,4 @@
+import { createObservation, toLegacyTelemetryLine } from './observability/index.js';
 import type { DelegationCostFields } from './services/cost-accounting.js';
 export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activated' | 'delegation_begin' | 'delegation_end' | 'task_state_changed' | 'gate_passed' | 'gate_failed' | 'gate_parse_error' | 'reviewer_gate_decision' | 'phase_changed' | 'budget_updated' | 'model_fallback' | 'hard_limit_hit' | 'revision_limit_hit' | 'loop_detected' | 'no_op_strong_warning' | 'scope_violation' | 'qa_skip_violation' | 'heartbeat' | 'turbo_mode_changed' | 'auto_oversight_escalation' | 'environment_detected' | 'evidence_lock_acquired' | 'evidence_lock_contended' | 'evidence_lock_stale_recovered' | 'plan_ledger_cas_retry' | 'plan_md_write_failed' | 'snapshot_failed' | 'gate_denial_loop'
 /**
@@ -25,7 +26,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**
@@ -157,4 +158,6 @@ export declare const _internals: {
     emit: typeof emit;
     rotateTelemetryIfNeeded: typeof rotateTelemetryIfNeeded;
     heartbeatListenerCount: () => number;
+    createObservation: typeof createObservation;
+    toLegacyTelemetryLine: typeof toLegacyTelemetryLine;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.136.5",
+	"version": "7.137.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -104,7 +104,8 @@
 		"prepare": "bun run build",
 		"repro:704": "node scripts/repro-704.mjs",
 		"repro:1144": "bun scripts/repro-1144.mjs",
-		"repro:1873": "bun build scripts/repro-1873-entry.ts --outdir dist-build-test/repro-1873 --target node --format esm && node scripts/repro-1873.mjs"
+		"repro:1873": "bun build scripts/repro-1873-entry.ts --outdir dist-build-test/repro-1873 --target node --format esm && node scripts/repro-1873.mjs",
+		"check:events": "bun run scripts/check-event-contract.ts"
 	},
 	"dependencies": {
 		"@opencode-ai/plugin": "^1.18.3",