@opensip-cli/core 0.1.0

package/dist/lib/run-timer.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Host-owned RunTimer / RunLifecycle primitive
+ * (host-owned-run-timing plan).
+ *
+ * Single source of truth for wall-clock start + monotonic elapsed for one
+ * user-visible CLI tool run. The host run-lifecycle plane creates one lifecycle
+ * inside the selected command action (after `RunScope` entry, before any
+ * tool-owned work) and `complete()`s it once the tool handler / live renderer
+ * returns its completion data — that frozen snapshot feeds the generic
+ * `StoredSession.startedAt` / `completedAt` / `durationMs`.
+ *
+ * Tools and engines must never capture their own `Date.now` / `new Date` for
+ * the generic session timing fields; only the host lifecycle feeds those.
+ * Internal tool timers (per-unit, per-stage, etc.) remain tool-owned for
+ * diagnostics.
+ *
+ * `startedAt` is ISO wall time captured at construction. `complete()` is
+ * idempotent: the first call freezes `completedAt` + `durationMs`; later calls
+ * return the same frozen snapshot. `snapshot()` reads live before completion
+ * (for the ticking live display) and the frozen values after. Elapsed uses a
+ * monotonic clock (`performance.now` when available) to avoid skew on long runs
+ * or system clock adjustments.
+ */
+/**
+ * Create a fresh host-owned run timer.
+ *
+ * Must be called by the CLI host after `RunScope` is entered (so `runId` etc.
+ * are available for logging in Phase 1 wiring) but before any tool work that
+ * will be timed.
+ */
+export function createRunTimer() {
+    const startedAt = new Date().toISOString();
+    const startedAtEpochMs = Date.now();
+    // Prefer a monotonic clock to avoid wall-time skew on long runs.
+    // In Node 16.7+ / modern browsers, `performance` is global and provides
+    // `performance.now()`. Fall back to Date math if unavailable.
+    const perfNow = typeof performance !== 'undefined' && typeof performance.now === 'function'
+        ? performance.now.bind(performance)
+        : undefined;
+    const monotonicStart = perfNow ? perfNow() : undefined;
+    function elapsedMs() {
+        const raw = monotonicStart !== undefined && perfNow
+            ? perfNow() - monotonicStart
+            : Date.now() - startedAtEpochMs;
+        return Math.max(0, raw);
+    }
+    let frozen;
+    function snapshot() {
+        if (frozen)
+            return frozen;
+        return {
+            startedAt,
+            completedAt: new Date().toISOString(),
+            durationMs: Math.max(0, elapsedMs()),
+        };
+    }
+    function complete() {
+        // Idempotent: the first completion freezes completedAt + durationMs.
+        frozen ??= {
+            startedAt,
+            completedAt: new Date().toISOString(),
+            durationMs: Math.max(0, elapsedMs()),
+        };
+        return frozen;
+    }
+    return {
+        startedAt,
+        startedAtEpochMs,
+        elapsedMs,
+        snapshot,
+        complete,
+    };
+}
+/**
+ * Create a fresh host-owned run lifecycle. Alias of {@link createRunTimer}
+ * under the spec-named factory (host-owned-run-timing §6.1).
+ */
+export const createRunLifecycle = createRunTimer;
+//# sourceMappingURL=run-timer.js.map

package/dist/lib/run-timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-timer.js","sourceRoot":"","sources":["../../src/lib/run-timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAqDH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEpC,iEAAiE;IACjE,wEAAwE;IACxE,8DAA8D;IAC9D,MAAM,OAAO,GACX,OAAO,WAAW,KAAK,WAAW,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU;QACzE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC;QACnC,CAAC,CAAC,SAAS,CAAC;IAEhB,MAAM,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEvD,SAAS,SAAS;QAChB,MAAM,GAAG,GACP,cAAc,KAAK,SAAS,IAAI,OAAO;YACrC,CAAC,CAAC,OAAO,EAAE,GAAG,cAAc;YAC5B,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,gBAAgB,CAAC;QACpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,MAAqC,CAAC;IAE1C,SAAS,QAAQ;QACf,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,OAAO;YACL,SAAS;YACT,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SACrC,CAAC;IACJ,CAAC;IAED,SAAS,QAAQ;QACf,qEAAqE;QACrE,MAAM,KAAK;YACT,SAAS;YACT,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;SACrC,CAAC;QACF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO;QACL,SAAS;QACT,gBAAgB;QAChB,SAAS;QACT,QAAQ;QACR,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAuB,cAAc,CAAC"}

package/dist/lib/scope-types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Scope type contracts — the leaf module that breaks the
+ * `RunScope ⟷ Tool` type cycle (audit 2026-05-29, M4).
+ *
+ * The cycle was `run-scope.ts → tools/registry.ts → tools/types.ts →
+ * run-scope.ts`: `RunScope` holds a `ToolRegistry` (→ `Tool`), and the
+ * `Tool` contract named the concrete `RunScope` back (via
+ * `ToolCliContext.scope` and the old `extendScope`). Both edges are
+ * type-only, so there is no runtime cycle — but it's a kernel smell and
+ * was invisible to the architecture gate (`tsPreCompilationDeps:false`).
+ *
+ * The fix is DIP: the `Tool` contract depends on the abstractions here,
+ * never on the concrete `RunScope`. This module imports NOTHING from
+ * `tools/` or `run-scope.ts`, so it is a true leaf — `tools/types.ts`
+ * can depend on it with no edge back to `run-scope.ts`.
+ *
+ * - `ToolScope`  — the Tool-FACING view of the scope (everything tools
+ *   read via `cli.scope.*`), deliberately WITHOUT the `tools`
+ *   `ToolRegistry` (which would re-introduce the `→ Tool` edge). Tools
+ *   never read `scope.tools`. `RunScope` is a `ToolScope` plus `tools`.
+ * - `ScopeContribution` — the augmentable slot bag a tool returns from
+ *   `Tool.contributeScope()`. Tools augment THIS (not `RunScope`); the
+ *   kernel `Object.assign`s it onto the scope. `RunScope`/`ToolScope`
+ *   inherit the slots for reading.
+ */
+import type { Logger } from './logger.js';
+import type { ProjectContext } from './project-context.js';
+import type { LanguageParseCache } from '../languages/parse-cache-class.js';
+import type { LanguageRegistry } from '../languages/registry.js';
+import type { SignalSink } from '../signals/signal-sink.js';
+/** Opaque slot for per-run recipe configuration (replaces globalThis Symbol). */
+export interface RecipeUnitConfigSlot {
+    get<T extends Record<string, unknown>>(slug: string): T | undefined;
+    set(slug: string, config: Record<string, unknown>): void;
+    setAll(config: Record<string, Record<string, unknown>>): void;
+    clear(): void;
+}
+/**
+ * The resolved, validated tool configuration for this run (launch,
+ * ADR-0023, Phase 4). `namespace -> { key -> value }`, where each top-level
+ * key is a tool's namespace (`graph`/`fitness`/`simulation`) after the host
+ * composed every tool's contributed schema, validated the document STRICT,
+ * and resolved precedence (flag > env > file > defaults).
+ *
+ * Structurally identical to `@opensip-cli/config`'s `ResolvedConfig`, kept
+ * Zod-free here so the kernel carries no config-layer dependency — the CLI
+ * (which DOES import `@opensip-cli/config`) writes it, and tools read their
+ * own namespace via `currentScope()?.toolConfig?.<namespace>`.
+ */
+export type ResolvedToolConfig = Record<string, Record<string, unknown>>;
+/**
+ * The structural shape of one registered target the host hands tools through
+ * `scope.targets`. A target is a named file set (`include`/`exclude` globs)
+ * plus its language/concern metadata. Kept structural (Zod-free, no
+ * `@opensip-cli/config` import) so the kernel carries no config-layer or
+ * tool-vocabulary dependency — it mirrors `ResolvedToolConfig`'s "structural
+ * analog of a config-layer type" pattern. `@opensip-cli/config`'s `Target`
+ * (a `{ config: TargetConfig }`) is structurally assignable to this shape.
+ */
+export interface TargetView {
+    readonly config: {
+        readonly name: string;
+        readonly description: string;
+        readonly include: readonly string[];
+        readonly exclude: readonly string[];
+        readonly tags?: readonly string[];
+        readonly languages?: readonly string[];
+        readonly concerns?: readonly string[];
+    };
+}
+/**
+ * The structural, host-built targeting accessor exposed on `scope.targets`
+ * (ADR-0037). Names only the generic methods the host and any tool call to
+ * resolve named targets to file sets and apply project-wide exclusions —
+ * never the concrete substrate class. `core` names no targeting concrete
+ * (it imports nothing workspace); the substrate's `TargetRegistry`, wrapped
+ * by the CLI bootstrap with the bound `resolveTargets`/`applyGlobalExcludes`
+ * closures + `globalExcludes` list, is structurally assignable here.
+ *
+ * Mirrors the `ResolvedToolConfig` precedent: a structural, Zod-free analog
+ * of a config-layer runtime, declared in the kernel leaf so the `Tool`
+ * contract can read it without a layer inversion.
+ */
+export interface TargetResolver {
+    /** Look up a registered target by its config name. */
+    getByName(name: string): TargetView | undefined;
+    /** Return every registered target. */
+    getAll(): readonly TargetView[];
+    /** Return every registered target whose `config.tags` include `tag`. */
+    getByTag(tag: string): readonly TargetView[];
+    /** Whether a target with the given name is registered. */
+    has(name: string): boolean;
+    /**
+     * Resolve the named targets to a deduplicated, sorted list of absolute file
+     * paths, applying per-target `exclude` AND the project `globalExcludes`.
+     */
+    resolveTargets(names: readonly string[], rootDir: string): readonly string[];
+    /** Filter a file list against the project `globalExcludes` (rootDir-relative). */
+    applyGlobalExcludes(files: readonly string[], rootDir: string): readonly string[];
+    /** The project-wide exclusion globs this resolver was built with. */
+    readonly globalExcludes: readonly string[];
+}
+/**
+ * Opaque accessor that lazily opens the datastore on first read.
+ * Returns `undefined` when no datastore is configured for this scope.
+ */
+export type DataStoreThunk = () => unknown;
+/**
+ * Per-tool subscope contribution. Each tool augments this interface from
+ * its own package (`declare module '@opensip-cli/core' { interface
+ * ScopeContribution { graph?: … } }`) and returns the matching object
+ * from `Tool.contributeScope()`. The kernel installs it onto the scope.
+ * `ToolScope` (and therefore `RunScope`) extends this, so the same slots
+ * are readable via `cli.scope.<tool>` / `currentScope()?.<tool>`.
+ *
+ * Empty here by design — every member arrives via tool augmentation, so
+ * core never names a tool-specific type.
+ */
+export interface ScopeContribution {
+}
+/**
+ * The Tool-facing view of the per-invocation scope: everything a tool
+ * reads through `ToolCliContext.scope`. Excludes the `tools`
+ * `ToolRegistry` on purpose — tools never read it, and naming it here
+ * would re-introduce the `Tool` reference that creates the cycle.
+ * `RunScope` is structurally a `ToolScope` with `tools` added.
+ */
+export interface ToolScope extends ScopeContribution {
+    readonly logger: Logger;
+    readonly parseCache: LanguageParseCache;
+    readonly recipeUnitConfig: RecipeUnitConfigSlot;
+    readonly projectContext: ProjectContext | undefined;
+    readonly datastore: DataStoreThunk;
+    readonly languages: LanguageRegistry;
+    readonly runId: string;
+    /** Cloud signal sink for this run (ADR-0008); `noopSignalSink` unless cloud sync is on. */
+    readonly signalSink: SignalSink;
+    /**
+     * The resolved, strict-validated tool configuration for this run (ADR-0023,
+     * Phase 4). Seeded by the CLI's pre-action-hook after composing every
+     * registered tool's contributed schema and validating the config document;
+     * absent on a scope built without a config document (e.g. a project-agnostic
+     * command, or a config-less project). A tool reads its own namespace
+     * (`scope.toolConfig?.graph`, `?.fitness`, `?.simulation`).
+     */
+    readonly toolConfig?: ResolvedToolConfig;
+    /**
+     * The strict-validated raw config document for this run (ADR-0023's
+     * one-reader invariant). Seeded by the CLI's pre-action-hook ONLY when a
+     * real `opensip-cli.config.yml` was read for this run — absent on a
+     * project-agnostic or config-less run, so a tool that hard-errors on a
+     * missing config (fitness) stays loud. Tools that project tool-specific
+     * shapes out of the document (fitness's signalers/targets loaders) parse
+     * THIS instead of re-reading the file: the host is the only runtime config
+     * reader; what remains in the tool is tool-specific projection and
+     * cross-validation. Structural (`Record<string, unknown>`) so the kernel
+     * carries no config-layer dependency — mirrors `ResolvedToolConfig`.
+     */
+    readonly configDocument?: Readonly<Record<string, unknown>>;
+    /**
+     * The host-built file-targeting accessor for this run (ADR-0037). Seeded by
+     * the CLI's pre-action-hook from the loaded config document's `targets:` /
+     * `globalExcludes:` blocks — built once per run, mirroring `toolConfig` and
+     * `languages`. Absent on a scope built without a config document (a
+     * project-agnostic command, a config-less project, or a project with no
+     * `targets:` block). Tools read it generically (`scope.targets?.resolveTargets`
+     * / `?.getByTag` / `?.applyGlobalExcludes`); the structural `TargetResolver`
+     * names no targeting concrete, so the kernel carries no targeting dependency.
+     */
+    readonly targets?: TargetResolver;
+}
+//# sourceMappingURL=scope-types.d.ts.map

package/dist/lib/scope-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-types.d.ts","sourceRoot":"","sources":["../../src/lib/scope-types.ts"],"names":[],"mappings":"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"}

package/dist/lib/scope-types.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Scope type contracts — the leaf module that breaks the
+ * `RunScope ⟷ Tool` type cycle (audit 2026-05-29, M4).
+ *
+ * The cycle was `run-scope.ts → tools/registry.ts → tools/types.ts →
+ * run-scope.ts`: `RunScope` holds a `ToolRegistry` (→ `Tool`), and the
+ * `Tool` contract named the concrete `RunScope` back (via
+ * `ToolCliContext.scope` and the old `extendScope`). Both edges are
+ * type-only, so there is no runtime cycle — but it's a kernel smell and
+ * was invisible to the architecture gate (`tsPreCompilationDeps:false`).
+ *
+ * The fix is DIP: the `Tool` contract depends on the abstractions here,
+ * never on the concrete `RunScope`. This module imports NOTHING from
+ * `tools/` or `run-scope.ts`, so it is a true leaf — `tools/types.ts`
+ * can depend on it with no edge back to `run-scope.ts`.
+ *
+ * - `ToolScope`  — the Tool-FACING view of the scope (everything tools
+ *   read via `cli.scope.*`), deliberately WITHOUT the `tools`
+ *   `ToolRegistry` (which would re-introduce the `→ Tool` edge). Tools
+ *   never read `scope.tools`. `RunScope` is a `ToolScope` plus `tools`.
+ * - `ScopeContribution` — the augmentable slot bag a tool returns from
+ *   `Tool.contributeScope()`. Tools augment THIS (not `RunScope`); the
+ *   kernel `Object.assign`s it onto the scope. `RunScope`/`ToolScope`
+ *   inherit the slots for reading.
+ */
+export {};
+//# sourceMappingURL=scope-types.js.map

package/dist/lib/scope-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-types.js","sourceRoot":"","sources":["../../src/lib/scope-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/lib/severity-policy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SeverityPolicy — the one home for severity mapping + the gate's error/warning
+ * predicate (north-star §5.9, launch).
+ *
+ * Severity lives at two levels: AUTHOR severity (`error | warning`, what a fitness
+ * check or graph rule declares) and WIRE severity (the 4-level
+ * {@link SignalSeverity} on the `Signal`). Previously the author→wire map was
+ * duplicated (fitness's `mapFindingSeverity` + `liftSeverity`) and the graph
+ * override (`applySeverityOverride`) lived apart, while the gate's error/warning
+ * counting was inlined in `buildSignalEnvelope`. This consolidates them so a
+ * change to severity semantics is one edit and every consumer agrees.
+ *
+ * The mappings are byte-identical to what they replace: `error → high`,
+ * `warning → medium` (UP, never collapsing, so the error-rung / warning-rung
+ * bucketing reproduces the historical counts), and the override clamps only when
+ * explicitly set (ADR-0005 / baseline-neutral).
+ */
+import { type SignalSeverity } from '../types/signal.js';
+/** The 2-level severity a check/rule author declares (mapped UP to the wire level). */
+export type AuthorSeverity = 'error' | 'warning';
+/**
+ * The central severity policy. A frozen namespace (not per-run state) — pure
+ * functions over the severity types, the single source of truth for author→wire
+ * mapping, the override clamp, and the error/warning predicate.
+ */
+export declare const SeverityPolicy: Readonly<{
+    /** Author `error|warning` → wire severity: `error → high`, `warning → medium`. */
+    readonly liftAuthorSeverity: (severity: AuthorSeverity) => SignalSeverity;
+    /**
+     * Clamp a base wire severity by an opt-in override (`error → high`,
+     * `warning → medium`); returns `base` unchanged when no override is set
+     * (baseline-neutral, ADR-0005).
+     */
+    readonly applyOverride: (base: SignalSeverity, override: AuthorSeverity | undefined) => SignalSeverity;
+    /** True when a severity is on the error rung (`critical`/`high`) — the gate predicate. */
+    readonly isError: (severity: SignalSeverity) => boolean;
+}>;
+//# sourceMappingURL=severity-policy.d.ts.map

package/dist/lib/severity-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity-policy.d.ts","sourceRoot":"","sources":["../../src/lib/severity-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE1E,uFAAuF;AACvF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,kFAAkF;4CACrD,cAAc,KAAG,cAAc;IAI5D;;;;OAIG;mCACiB,cAAc,YAAY,cAAc,GAAG,SAAS,KAAG,cAAc;IAKzF,0FAA0F;iCACxE,cAAc,KAAG,OAAO;EAGjC,CAAC"}

package/dist/lib/severity-policy.js

@@ -0,0 +1,44 @@
+/**
+ * SeverityPolicy — the one home for severity mapping + the gate's error/warning
+ * predicate (north-star §5.9, launch).
+ *
+ * Severity lives at two levels: AUTHOR severity (`error | warning`, what a fitness
+ * check or graph rule declares) and WIRE severity (the 4-level
+ * {@link SignalSeverity} on the `Signal`). Previously the author→wire map was
+ * duplicated (fitness's `mapFindingSeverity` + `liftSeverity`) and the graph
+ * override (`applySeverityOverride`) lived apart, while the gate's error/warning
+ * counting was inlined in `buildSignalEnvelope`. This consolidates them so a
+ * change to severity semantics is one edit and every consumer agrees.
+ *
+ * The mappings are byte-identical to what they replace: `error → high`,
+ * `warning → medium` (UP, never collapsing, so the error-rung / warning-rung
+ * bucketing reproduces the historical counts), and the override clamps only when
+ * explicitly set (ADR-0005 / baseline-neutral).
+ */
+import { isErrorSeverity } from '../types/signal.js';
+/**
+ * The central severity policy. A frozen namespace (not per-run state) — pure
+ * functions over the severity types, the single source of truth for author→wire
+ * mapping, the override clamp, and the error/warning predicate.
+ */
+export const SeverityPolicy = Object.freeze({
+    /** Author `error|warning` → wire severity: `error → high`, `warning → medium`. */
+    liftAuthorSeverity(severity) {
+        return severity === 'error' ? 'high' : 'medium';
+    },
+    /**
+     * Clamp a base wire severity by an opt-in override (`error → high`,
+     * `warning → medium`); returns `base` unchanged when no override is set
+     * (baseline-neutral, ADR-0005).
+     */
+    applyOverride(base, override) {
+        if (override === undefined)
+            return base;
+        return override === 'error' ? 'high' : 'medium';
+    },
+    /** True when a severity is on the error rung (`critical`/`high`) — the gate predicate. */
+    isError(severity) {
+        return isErrorSeverity(severity);
+    },
+});
+//# sourceMappingURL=severity-policy.js.map

package/dist/lib/severity-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"severity-policy.js","sourceRoot":"","sources":["../../src/lib/severity-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAuB,MAAM,oBAAoB,CAAC;AAK1E;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,kFAAkF;IAClF,kBAAkB,CAAC,QAAwB;QACzC,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,IAAoB,EAAE,QAAoC;QACtE,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClD,CAAC;IAED,0FAA0F;IAC1F,OAAO,CAAC,QAAwB;QAC9B,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;CACO,CAAC,CAAC"}

package/dist/lib/telemetry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Tracing primitive for opensip-cli — the kernel sibling of `logger`.
+ *
+ * This module is a thin wrapper over the **OpenTelemetry API** (`@opentelemetry/api`)
+ * — the no-op facade half of OTel's library/application split. It exposes a
+ * narrow tracing seam (`getTracer`, `withSpan`) that every tool uses to emit
+ * spans, exactly as every tool emits logs through `logger`.
+ *
+ * ## No-op-until-SDK contract (load-bearing for standalone users)
+ *
+ * The OpenTelemetry **API** does nothing on its own. Until an SDK registers a
+ * global `TracerProvider`, `trace.getTracer(...)` returns a *no-op tracer*:
+ * `startActiveSpan` runs the callback with a no-op span, records nothing, makes
+ * no network calls, and adds an unmeasurable amount of overhead. That
+ * registration happens ONLY at the application boundary — the CLI composition
+ * root (`opensip-cli`), gated on `OTEL_EXPORTER_OTLP_ENDPOINT`. The heavy
+ * SDK packages (`@opentelemetry/sdk-*`, exporters, context managers) never enter
+ * the kernel.
+ *
+ * The consequence: importing and calling `withSpan` from a standalone CLI run
+ * (no OTLP endpoint configured) is a hard no-op — `fn` runs, its value is
+ * returned, and nothing is emitted. This is the guarantee standalone users
+ * depend on, and it is asserted in `__tests__/telemetry.test.ts`.
+ */
+import { type Span, type Attributes, type Meter, type Tracer } from '@opentelemetry/api';
+/**
+ * Resolve a `Tracer` for a given instrumentation scope name (e.g.
+ * `'opensip-cli-graph'`). Reads the *global* tracer provider set by the SDK
+ * at the application boundary; returns a no-op tracer when no SDK is registered.
+ */
+export declare function getTracer(name: string): Tracer;
+/**
+ * Run `fn` inside an active span.
+ *
+ * Records exceptions and sets ERROR status if `fn` throws, and always ends the
+ * span. When no SDK is registered the underlying tracer is a no-op, so this adds
+ * an unmeasurable amount of overhead — see the no-op-until-SDK contract above.
+ *
+ * Synchronous by design: graph's `runStage` (the first consumer) is synchronous,
+ * so `fn` returns `T` and the span ends when the callback returns. An async
+ * caller passes an async `fn` and the helper returns its promise — but note the
+ * span ends when the synchronous callback returns, so an async caller that wants
+ * the span to span the awaited work should `return await fn()` from inside an
+ * async `fn` whose promise the helper returns (i.e. `withSpan(name, span, async () => { ... })`).
+ *
+ * @param tracerName instrumentation scope (passed to {@link getTracer})
+ * @param spanName   the span name
+ * @param fn         the work to run inside the span
+ * @param attrs      optional attributes set on the span before `fn` runs
+ */
+export declare function withSpan<T>(tracerName: string, spanName: string, fn: (span: Span) => T, attrs?: Attributes): T;
+/**
+ * Async sibling of {@link withSpan}: the span stays open across awaited work and
+ * ends only when the returned promise settles.
+ *
+ * {@link withSpan} is synchronous — its `finally` runs the instant the callback
+ * returns, so wrapping awaited work with it would end the span before the work
+ * completes and miss async rejections. Use this for any `fn` that returns a
+ * promise. The span stays active for the duration of the awaited work (under the
+ * SDK's AsyncLocalStorage context manager), so descendants — including spans
+ * emitted by spawned subprocesses that inherit {@link currentTraceparent} — nest
+ * under it. Same no-op-until-SDK contract: a hard no-op when no SDK is registered.
+ *
+ * @param tracerName instrumentation scope (passed to {@link getTracer})
+ * @param spanName   the span name
+ * @param fn         the async work to run inside the span
+ * @param attrs      optional attributes set on the span before `fn` runs
+ */
+export declare function withSpanAsync<T>(tracerName: string, spanName: string, fn: (span: Span) => Promise<T>, attrs?: Attributes): Promise<T>;
+/**
+ * Serialize the currently-active span context to a W3C `traceparent` string, for
+ * propagation into a spawned subprocess (passed as the `TRACEPARENT` env var,
+ * which {@link initTelemetry} extracts at the child's boundary so its spans nest
+ * under ours).
+ *
+ * Returns `undefined` when there is no active recording span — which includes
+ * every standalone run, since the no-op tracer produces an invalid (all-zero)
+ * span context that the W3C propagator declines to emit. Uses the globally
+ * registered propagator (installed by the SDK at the application boundary), so
+ * the kernel stays a pure `@opentelemetry/api` consumer with no SDK dependency.
+ */
+export declare function currentTraceparent(): string | undefined;
+/**
+ * Resolve a `Meter` for a given instrumentation scope name (e.g.
+ * `'opensip-cli'`). Reads the *global* meter provider set by the SDK
+ * at the application boundary; returns a no-op meter when no SDK is registered.
+ *
+ * Same no-op-until-SDK contract as tracing. SDK registration (including
+ * `@opentelemetry/sdk-metrics`) happens only in the CLI composition root,
+ * gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ */
+export declare function getMeter(name: string): Meter;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/lib/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAML,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EACrB,KAAK,CAAC,EAAE,UAAU,GACjB,CAAC,CAgBH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9B,KAAK,CAAC,EAAE,UAAU,GACjB,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAIvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAE5C"}

package/dist/lib/telemetry.js

@@ -0,0 +1,144 @@
+// @fitness-ignore-file detached-promises -- OTel Span methods (recordException/setStatus/end) return void (sync); the heuristic flags them inside withSpanAsync's async callback. The only promise here (fn(span)) is awaited.
+/**
+ * Tracing primitive for opensip-cli — the kernel sibling of `logger`.
+ *
+ * This module is a thin wrapper over the **OpenTelemetry API** (`@opentelemetry/api`)
+ * — the no-op facade half of OTel's library/application split. It exposes a
+ * narrow tracing seam (`getTracer`, `withSpan`) that every tool uses to emit
+ * spans, exactly as every tool emits logs through `logger`.
+ *
+ * ## No-op-until-SDK contract (load-bearing for standalone users)
+ *
+ * The OpenTelemetry **API** does nothing on its own. Until an SDK registers a
+ * global `TracerProvider`, `trace.getTracer(...)` returns a *no-op tracer*:
+ * `startActiveSpan` runs the callback with a no-op span, records nothing, makes
+ * no network calls, and adds an unmeasurable amount of overhead. That
+ * registration happens ONLY at the application boundary — the CLI composition
+ * root (`opensip-cli`), gated on `OTEL_EXPORTER_OTLP_ENDPOINT`. The heavy
+ * SDK packages (`@opentelemetry/sdk-*`, exporters, context managers) never enter
+ * the kernel.
+ *
+ * The consequence: importing and calling `withSpan` from a standalone CLI run
+ * (no OTLP endpoint configured) is a hard no-op — `fn` runs, its value is
+ * returned, and nothing is emitted. This is the guarantee standalone users
+ * depend on, and it is asserted in `__tests__/telemetry.test.ts`.
+ */
+import { context, metrics, propagation, trace, SpanStatusCode, } from '@opentelemetry/api';
+/**
+ * Resolve a `Tracer` for a given instrumentation scope name (e.g.
+ * `'opensip-cli-graph'`). Reads the *global* tracer provider set by the SDK
+ * at the application boundary; returns a no-op tracer when no SDK is registered.
+ */
+export function getTracer(name) {
+    return trace.getTracer(name);
+}
+/**
+ * Run `fn` inside an active span.
+ *
+ * Records exceptions and sets ERROR status if `fn` throws, and always ends the
+ * span. When no SDK is registered the underlying tracer is a no-op, so this adds
+ * an unmeasurable amount of overhead — see the no-op-until-SDK contract above.
+ *
+ * Synchronous by design: graph's `runStage` (the first consumer) is synchronous,
+ * so `fn` returns `T` and the span ends when the callback returns. An async
+ * caller passes an async `fn` and the helper returns its promise — but note the
+ * span ends when the synchronous callback returns, so an async caller that wants
+ * the span to span the awaited work should `return await fn()` from inside an
+ * async `fn` whose promise the helper returns (i.e. `withSpan(name, span, async () => { ... })`).
+ *
+ * @param tracerName instrumentation scope (passed to {@link getTracer})
+ * @param spanName   the span name
+ * @param fn         the work to run inside the span
+ * @param attrs      optional attributes set on the span before `fn` runs
+ */
+export function withSpan(tracerName, spanName, fn, attrs) {
+    return getTracer(tracerName).startActiveSpan(spanName, (span) => {
+        if (attrs)
+            span.setAttributes(attrs);
+        try {
+            return fn(span);
+        }
+        catch (error) {
+            // Normalize before recording: a thrown non-Error (string, object) must
+            // record as a message rather than be unsafely cast to Error. OTel's
+            // `recordException` accepts `string | Exception`, so this is type-safe.
+            span.recordException(error instanceof Error ? error : String(error));
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Async sibling of {@link withSpan}: the span stays open across awaited work and
+ * ends only when the returned promise settles.
+ *
+ * {@link withSpan} is synchronous — its `finally` runs the instant the callback
+ * returns, so wrapping awaited work with it would end the span before the work
+ * completes and miss async rejections. Use this for any `fn` that returns a
+ * promise. The span stays active for the duration of the awaited work (under the
+ * SDK's AsyncLocalStorage context manager), so descendants — including spans
+ * emitted by spawned subprocesses that inherit {@link currentTraceparent} — nest
+ * under it. Same no-op-until-SDK contract: a hard no-op when no SDK is registered.
+ *
+ * @param tracerName instrumentation scope (passed to {@link getTracer})
+ * @param spanName   the span name
+ * @param fn         the async work to run inside the span
+ * @param attrs      optional attributes set on the span before `fn` runs
+ */
+export async function withSpanAsync(tracerName, spanName, fn, attrs) {
+    return getTracer(tracerName).startActiveSpan(spanName, async (span) => {
+        if (attrs)
+            span.setAttributes(attrs);
+        try {
+            return await fn(span);
+        }
+        catch (error) {
+            span.recordException(error instanceof Error ? error : String(error));
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Serialize the currently-active span context to a W3C `traceparent` string, for
+ * propagation into a spawned subprocess (passed as the `TRACEPARENT` env var,
+ * which {@link initTelemetry} extracts at the child's boundary so its spans nest
+ * under ours).
+ *
+ * Returns `undefined` when there is no active recording span — which includes
+ * every standalone run, since the no-op tracer produces an invalid (all-zero)
+ * span context that the W3C propagator declines to emit. Uses the globally
+ * registered propagator (installed by the SDK at the application boundary), so
+ * the kernel stays a pure `@opentelemetry/api` consumer with no SDK dependency.
+ */
+export function currentTraceparent() {
+    const carrier = {};
+    propagation.inject(context.active(), carrier);
+    return carrier.traceparent;
+}
+/**
+ * Resolve a `Meter` for a given instrumentation scope name (e.g.
+ * `'opensip-cli'`). Reads the *global* meter provider set by the SDK
+ * at the application boundary; returns a no-op meter when no SDK is registered.
+ *
+ * Same no-op-until-SDK contract as tracing. SDK registration (including
+ * `@opentelemetry/sdk-metrics`) happens only in the CLI composition root,
+ * gated on `OTEL_EXPORTER_OTLP_ENDPOINT`.
+ */
+export function getMeter(name) {
+    return metrics.getMeter(name);
+}
+// Profiling support is intentionally minimal in core (thin seam only).
+// The actual profiler (labels, start/stop, flush) lives in the CLI root
+// (`packages/cli/src/telemetry/profiling.ts`) behind the OPENSIP_PROFILING
+// (recommended) + OTEL_EXPORTER_OTLP_ENDPOINT gate (or OTEL-only mode).
+// Core only provides correlation primitives (currentTraceparent, runId via scope)
+// that the CLI uses to label profiles. This keeps the kernel free of any
+// profiling SDK bits. See ADR-0049 and the observability-hardening plan.
+//# sourceMappingURL=telemetry.js.map

package/dist/lib/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":"AAAA,+NAA+N;AAC/N;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,OAAO,EACP,OAAO,EACP,WAAW,EACX,KAAK,EACL,cAAc,GAKf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAkB,EAClB,QAAgB,EAChB,EAAqB,EACrB,KAAkB;IAElB,OAAO,SAAS,CAAC,UAAU,CAAC,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QAC9D,IAAI,KAAK;YAAE,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,uEAAuE;YACvE,oEAAoE;YACpE,wEAAwE;YACxE,IAAI,CAAC,eAAe,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACrE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/C,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAkB,EAClB,QAAgB,EAChB,EAA8B,EAC9B,KAAkB;IAElB,OAAO,SAAS,CAAC,UAAU,CAAC,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QACpE,IAAI,KAAK;YAAE,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,eAAe,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACrE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/C,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC,WAAW,CAAC;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,uEAAuE;AACvE,wEAAwE;AACxE,2EAA2E;AAC3E,wEAAwE;AACxE,kFAAkF;AAClF,yEAAyE;AACzE,yEAAyE"}