feat(core-shared/instrumentation): withSpan returns Instrumented<F>

packages/core-shared/src/instrumentation/with-span.ts

@@ -1,12 +1,16 @@
 import type { ITracer, SpanOpts } from "./tracer.interface";
+import type { Instrumented } from "../conformance/brands";
 
 export function withSpan<Args extends unknown[], R>(
   tracer: ITracer,
   opts: SpanOpts | ((args: Args) => SpanOpts),
   fn: (...args: Args) => Promise<R>,
-): (...args: Args) => Promise<R> {
-  return (...args) => {
+): Instrumented<(...args: Args) => Promise<R>> {
+  const wrapped: (...args: Args) => Promise<R> = (...args) => {
     const resolved = typeof opts === "function" ? opts(args) : opts;
     return tracer.startSpan(resolved, () => fn(...args));
   };
+  // Cast is the only runtime concession — the brand is a phantom type;
+  // there is no real `__instrumented` property at runtime.
+  return wrapped as Instrumented<(...args: Args) => Promise<R>>;
 }