feat(core-shared/conformance): Instrumented<F> and Captured<F> brand types

packages/core-shared/src/conformance/brands.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expectTypeOf } from "vitest";
+import type { Instrumented, Captured } from "@/conformance/brands";
+
+describe("brand types", () => {
+  it("Instrumented<F> is structurally F plus a phantom flag", () => {
+    type Fn = (n: number) => Promise<string>;
+    expectTypeOf<Instrumented<Fn>>().toBeCallableWith(1);
+    expectTypeOf<Instrumented<Fn>>().returns.resolves.toEqualTypeOf<string>();
+    // The flag is readonly and required for assignability checks.
+    expectTypeOf<Instrumented<Fn>["__instrumented"]>().toEqualTypeOf<true>();
+  });
+
+  it("Captured<F> is structurally F plus a phantom flag", () => {
+    type Fn = (n: number) => Promise<string>;
+    expectTypeOf<Captured<Fn>>().toBeCallableWith(1);
+    expectTypeOf<Captured<Fn>["__captured"]>().toEqualTypeOf<true>();
+  });
+
+  it("brands compose without conflict", () => {
+    type Fn = (n: number) => Promise<string>;
+    type Both = Instrumented<Fn> & Captured<Fn>;
+    expectTypeOf<Both>().toBeCallableWith(1);
+    expectTypeOf<Both["__instrumented"]>().toEqualTypeOf<true>();
+    expectTypeOf<Both["__captured"]>().toEqualTypeOf<true>();
+  });
+});

packages/core-shared/src/conformance/brands.ts

@@ -0,0 +1,9 @@
+/**
+ * Phantom-type brands attached at wrap time by `withSpan`, `withCapture`,
+ * and `withAudit`. Pure type-level — no runtime cost, no proxy, no
+ * `Object.assign`. The conformance system uses these as the type-level
+ * seam the binding signature checks; a use-case factory that hasn't been
+ * wrapped is not assignable to a `ProductionUseCase<...>` slot.
+ */
+export type Instrumented<F> = F & { readonly __instrumented: true };
+export type Captured<F> = F & { readonly __captured: true };