diff --git a/docs/work/conformance-system-v1/02-boot-assertions/_story.md b/docs/work/conformance-system-v1/02-boot-assertions/_story.md new file mode 100644 index 0000000..3eb605b --- /dev/null +++ b/docs/work/conformance-system-v1/02-boot-assertions/_story.md @@ -0,0 +1,65 @@ +--- +id: 02-boot-assertions +epic: conformance-system-v1 +title: assertFeatureConformance + boot wiring +type: technical-story +status: done +feature: core-shared +depends-on: [01-define-feature-helper] +blocks: [03-eslint-rules] +--- + +## Goal +Runtime boot-time verification that every manifest-declared use case is bound +through the brand-attaching wrappers. Each feature's `bindProductionX(ctx)` +self-asserts at the tail; `pnpm dev` refuses to boot on drift. + +## Why +Type casts can mask unwrapped factories; manifest edits can drift from +binders without TypeScript noticing. Boot assertions catch what the type +system can't see — at zero cost during the inner agent feedback loop, and +synchronously at startup so failures fire loudly. + +## Done when +- `withSpan`, `withCapture`, `withAudit` attach non-enumerable runtime markers + matching the type-level brand names +- `assertFeatureConformance(container, manifest, symbols, ctx)` resolves each + manifest use case and throws `ConformanceError` on a missing brand +- `auth.bindProductionAuth(ctx)` self-asserts at the tail +- `pnpm dev` boots cleanly for the existing `auth` wiring; rebinding `signIn` + with an unwrapped factory causes `pnpm dev` to throw at startup + +## In scope +- Runtime marker attachment via `Object.defineProperty(fn, "__brand", { … })` + (non-enumerable, non-writable, non-configurable) +- `isInstrumented` / `isCaptured` / `isAudited` predicates +- `ConformanceError` class (extends `Error`) +- `assertFeatureConformance(container, manifest, symbols, ctx)` helper +- Wiring into `packages/auth/src/di/bind-production.ts` (tail-of-binder + self-assertion) +- `withAudit` upgraded from passthrough to a thin wrapper that attaches its + runtime brand without changing observable behaviour + +## Out of scope +- `assertConformance` over a multi-feature container collection at the app's + `bindAll()` (current per-feature self-assertion is sufficient and + forward-compatible) +- Wiring boot assertions into `cms` and `web-tanstack` — neither has a + `bind-production.ts` yet; they'll inherit the check whenever they grow one +- Manifests for `blog`, `media`, `navigation`, `marketing-pages` (their + `bindProductionX` stays unchanged in this story) +- Automated audit recording driven by manifest `audits[]` declarations + (deferred to a later story) + +## Tasks +- [x] Re-export `authManifest` from auth root barrel +- [x] TODO breadcrumb in `withAudit` pointing at future automation +- [x] Runtime marker helpers (`attachBrand`, `isInstrumented`, `isCaptured`, `isAudited`) +- [x] `withSpan` attaches runtime `__instrumented` marker +- [x] `withCapture` attaches runtime `__captured` marker +- [x] `withAudit` wraps + attaches runtime `__audited` marker +- [x] `ConformanceError` class +- [x] `assertFeatureConformance` helper + tests +- [x] Conformance barrel + subpath exports updated +- [x] `bindProductionAuth` self-asserts at the tail +- [x] Final verification + story closeout diff --git a/docs/work/conformance-system-v1/_epic.md b/docs/work/conformance-system-v1/_epic.md index a5962fe..befb3d7 100644 --- a/docs/work/conformance-system-v1/_epic.md +++ b/docs/work/conformance-system-v1/_epic.md @@ -31,7 +31,7 @@ See `docs/architecture/feature-conformance-explainer.html` and ## Stories - [x] [01 — defineFeature helper + Instrumented/Captured/Audited brands](01-define-feature-helper/_story.md) -- [ ] 02 — `assertConformance` + boot wiring (later plan) +- [x] [02 — `assertFeatureConformance` + boot wiring](02-boot-assertions/_story.md) - [ ] 03 — AST-aware ESLint rules (later plan) - [ ] 04 — CI drift gate (later plan) - [ ] 05 — Generator emits manifest + contracts + test stubs (later plan) diff --git a/packages/auth/src/di/bind-production.ts b/packages/auth/src/di/bind-production.ts index 94d5868..b422fb0 100644 --- a/packages/auth/src/di/bind-production.ts +++ b/packages/auth/src/di/bind-production.ts @@ -6,7 +6,9 @@ import { type ILogger, } from "@repo/core-shared/instrumentation"; import type { BindProductionContext } from "@repo/core-shared/di"; +import { assertFeatureConformance } from "@repo/core-shared/conformance"; import type { ProductionUseCase } from "@repo/core-shared/conformance"; +import { authManifest } from "../feature.manifest"; import type { AuthManifest } from "../feature.manifest"; import type { SignInInput, @@ -158,4 +160,17 @@ export function bindProductionAuth(ctx: BindProductionContext): void { // // // + + // Boot-time conformance check: refuses to start if any use-case binding + // is missing a required brand (withSpan / withCapture / withAudit). + assertFeatureConformance( + authContainer, + authManifest, + { + signIn: AUTH_SYMBOLS.ISignInUseCase, + signUp: AUTH_SYMBOLS.ISignUpUseCase, + signOut: AUTH_SYMBOLS.ISignOutUseCase, + }, + ctx, + ); } diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts index c067ff8..d400d0d 100644 --- a/packages/auth/src/index.ts +++ b/packages/auth/src/index.ts @@ -43,3 +43,8 @@ export { type UserSignedUpEvent, } from "./events/user-signed-up.event"; // + +// Feature conformance manifest (added in conformance milestone i, exposed +// here in milestone ii so the boot-time assertion and future tooling can +// read the contract from the package boundary). +export { authManifest, type AuthManifest } from "./feature.manifest"; diff --git a/packages/core-audit/src/with-audit.chain.test.ts b/packages/core-audit/src/with-audit.chain.test.ts new file mode 100644 index 0000000..232a2f3 --- /dev/null +++ b/packages/core-audit/src/with-audit.chain.test.ts @@ -0,0 +1,76 @@ +import { describe, it, expect, vi } from "vitest"; +import { withSpan } from "@repo/core-shared/instrumentation"; +import { withCapture } from "@repo/core-shared/instrumentation"; +import { isInstrumented, isCaptured, isAudited } from "@repo/core-shared/conformance"; +import { withAudit } from "@/with-audit"; +import type { IAuditLog } from "@/audit-log.interface"; +import type { ITracer, ISpan } from "@repo/core-shared/instrumentation"; +import type { ILogger } from "@repo/core-shared/instrumentation"; + +function makeTracer(): ITracer { + return { + startSpan: vi.fn(async (_opts, fn) => { + const span: ISpan = { setAttribute: () => {}, setStatus: () => {} }; + return fn(span); + }), + }; +} + +function makeLogger(): ILogger { + return { + captureException: vi.fn(), + captureMessage: vi.fn(), + addBreadcrumb: vi.fn(), + setUser: vi.fn(), + }; +} + +function makeAuditLog(): IAuditLog { + return { + record: vi.fn().mockResolvedValue(undefined), + eraseSubject: vi.fn().mockResolvedValue(undefined), + }; +} + +describe("brand propagation across the full wrapper chain", () => { + it("withSpan(withCapture(withAudit(fn))) carries all three brands on the outer wrapper", () => { + const tracer = makeTracer(); + const logger = makeLogger(); + const auditLog = makeAuditLog(); + const fn = async (input: { id: string }) => ({ ok: true, id: input.id }); + + const wrapped = withSpan( + tracer, + { name: "test.chain", op: "use-case" }, + withCapture( + logger, + { feature: "test", layer: "use-case" }, + withAudit(auditLog, fn), + ), + ); + + expect(isInstrumented(wrapped)).toBe(true); + expect(isCaptured(wrapped)).toBe(true); + expect(isAudited(wrapped)).toBe(true); + }); + + it("the full chain preserves input/output behaviour end-to-end", async () => { + const tracer = makeTracer(); + const logger = makeLogger(); + const auditLog = makeAuditLog(); + const fn = async (input: { id: string }) => ({ ok: true, id: input.id }); + + const wrapped = withSpan( + tracer, + { name: "test.chain", op: "use-case" }, + withCapture( + logger, + { feature: "test", layer: "use-case" }, + withAudit(auditLog, fn), + ), + ); + + const result = await wrapped({ id: "abc" }); + expect(result).toEqual({ ok: true, id: "abc" }); + }); +}); diff --git a/packages/core-audit/src/with-audit.test.ts b/packages/core-audit/src/with-audit.test.ts index 0ab2e8b..731be28 100644 --- a/packages/core-audit/src/with-audit.test.ts +++ b/packages/core-audit/src/with-audit.test.ts @@ -1,6 +1,7 @@ import { describe, it, expect, expectTypeOf, vi } from "vitest"; import { withAudit, type Audited } from "@/with-audit"; import type { IAuditLog } from "@/audit-log.interface"; +import { isAudited } from "@repo/core-shared/conformance"; function makeAuditLog(): IAuditLog { return { @@ -17,6 +18,22 @@ describe("withAudit", () => { expectTypeOf(wrapped).toMatchTypeOf>(); }); + it("attaches __audited as a non-enumerable property on the wrapped function", () => { + const auditLog = makeAuditLog(); + const fn = async () => ({ ok: true }); + const wrapped = withAudit(auditLog, fn); + expect(isAudited(wrapped)).toBe(true); + expect(Object.keys(wrapped)).not.toContain("__audited"); + }); + + it("does NOT pollute the original input function with the brand", () => { + const auditLog = makeAuditLog(); + const fn = async () => ({ ok: true }); + const wrapped = withAudit(auditLog, fn); + expect(isAudited(fn)).toBe(false); + expect(wrapped).not.toBe(fn); + }); + it("passes input and output through unchanged", async () => { const auditLog = makeAuditLog(); const fn = async (input: { id: string }) => ({ ok: true, id: input.id }); diff --git a/packages/core-audit/src/with-audit.ts b/packages/core-audit/src/with-audit.ts index a521816..89d0af7 100644 --- a/packages/core-audit/src/with-audit.ts +++ b/packages/core-audit/src/with-audit.ts @@ -1,34 +1,36 @@ import type { IAuditLog } from "./audit-log.interface"; +import { attachBrand } from "@repo/core-shared/conformance"; /** * Phantom-type brand attached at wrap time by `withAudit`. The conformance * system uses this as the type-level seam for mutating use cases that * declare `audits: [...]` in their manifest — without `__audited`, the * binding is not assignable to `ProductionUseCase` when M demands - * it. + * it. At runtime the brand is a non-enumerable property attached by + * `attachBrand` from `@repo/core-shared/conformance`, so the boot-time + * assertion can verify the binding went through the audit-aware path. */ export type Audited = F & { readonly __audited: true }; /** - * Use-case wrapper applied at DI bind time. In milestone i this is a - * brand-only attachment: it does not yet automatically call `auditLog.record`. - * Use cases continue to call `auditLog.record(...)` in their own bodies; the - * wrapper exists to make "binding was bound through the audit-aware path" - * type-checkable at compile time. - * - * A future story may move auditing logic out of factory bodies and into the - * wrapper itself (driven by manifest declarations) — but that requires the - * manifest's `audits[]` entries to fully specify what gets recorded, which - * is out of scope here. + * Use-case wrapper applied at DI bind time. The wrapper is a thin closure + * that forwards to `fn` unchanged and carries the `__audited` brand. The + * forward closure (instead of returning `fn` directly) keeps the brand on + * a fresh function so the caller's original `fn` is not mutated — important + * when the same factory output is used elsewhere unwrapped (dev-seed paths, + * tests). */ export function withAudit( - // The auditLog is part of the signature for two reasons: (1) callers must - // pass it at bind time, ensuring the dep is available, and (2) future - // versions of this wrapper will use it to emit audit events from the - // declarative manifest entry directly. + // TODO(conformance milestone iii+): wire automated recording from manifest + // `audits[]` declarations. For now, the wrapper exists to: + // (1) require callers to pass the auditLog at bind time (dep is available) + // (2) attach the `__audited` brand so the boot-time assertion can verify + // mutating use cases were bound through the audit-aware path. auditLog: IAuditLog, fn: (...args: Args) => Promise, ): Audited<(...args: Args) => Promise> { void auditLog; - return fn as Audited<(...args: Args) => Promise>; + const wrapped: (...args: Args) => Promise = (...args) => fn(...args); + attachBrand(wrapped, "__audited"); + return wrapped as Audited<(...args: Args) => Promise>; } diff --git a/packages/core-shared/src/conformance/assert-bindings.test.ts b/packages/core-shared/src/conformance/assert-bindings.test.ts new file mode 100644 index 0000000..4d26263 --- /dev/null +++ b/packages/core-shared/src/conformance/assert-bindings.test.ts @@ -0,0 +1,210 @@ +import { describe, it, expect, vi } from "vitest"; +import "reflect-metadata"; +import { Container } from "inversify"; +import { defineFeature } from "@/conformance/define-feature"; +import { ConformanceError } from "@/conformance/conformance-error"; +import { assertFeatureConformance } from "@/conformance/assert-bindings"; +import { withSpan } from "@/instrumentation/with-span"; +import { withCapture } from "@/instrumentation/with-capture"; +import type { ITracer, ISpan } from "@/instrumentation/tracer.interface"; +import type { ILogger } from "@/instrumentation/logger.interface"; +import type { BindContext } from "@/di/bind-context"; + +function makeTracer(): ITracer { + return { + startSpan: vi.fn(async (_opts, fn) => { + const span: ISpan = { setAttribute: () => {}, setStatus: () => {} }; + return fn(span); + }), + }; +} + +function makeLogger(): ILogger { + return { + captureException: vi.fn(), + captureMessage: vi.fn(), + addBreadcrumb: vi.fn(), + setUser: vi.fn(), + }; +} + +function makeCtx(): BindContext { + return { tracer: makeTracer(), logger: makeLogger() }; +} + +describe("assertFeatureConformance", () => { + it("passes when every use case is bound through withSpan + withCapture", () => { + const container = new Container(); + const sym = Symbol("test.signIn"); + const ctx = makeCtx(); + const bound = withSpan( + ctx.tracer, + { name: "test.signIn", op: "use-case" }, + withCapture(ctx.logger, { feature: "test", layer: "use-case" }, async (x: number) => x + 1), + ); + container.bind(sym).toConstantValue(bound); + + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signIn: { mutates: false, audits: [], publishes: [], consumes: [] }, + }, + realtimeChannels: [], + jobs: [], + } as const); + + expect(() => + assertFeatureConformance(container, manifest, { signIn: sym }, ctx), + ).not.toThrow(); + }); + + it("throws when a use case binding is missing the __instrumented brand", () => { + const container = new Container(); + const sym = Symbol("test.signIn"); + const ctx = makeCtx(); + const unwrapped = async (x: number) => x + 1; + container.bind(sym).toConstantValue(unwrapped); + + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signIn: { mutates: false, audits: [], publishes: [], consumes: [] }, + }, + realtimeChannels: [], + jobs: [], + } as const); + + expect(() => + assertFeatureConformance(container, manifest, { signIn: sym }, ctx), + ).toThrow(ConformanceError); + expect(() => + assertFeatureConformance(container, manifest, { signIn: sym }, ctx), + ).toThrow(/test\.signIn.*__instrumented/); + }); + + it("throws when a use case binding is missing the __captured brand", () => { + const container = new Container(); + const sym = Symbol("test.signIn"); + const ctx = makeCtx(); + // withSpan-only — no withCapture wrap + const partial = withSpan( + ctx.tracer, + { name: "test.signIn", op: "use-case" }, + async (x: number) => x + 1, + ); + container.bind(sym).toConstantValue(partial); + + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signIn: { mutates: false, audits: [], publishes: [], consumes: [] }, + }, + realtimeChannels: [], + jobs: [], + } as const); + + expect(() => + assertFeatureConformance(container, manifest, { signIn: sym }, ctx), + ).toThrow(/__captured/); + }); + + it("throws when a mutating use case with audits is missing the __audited brand", () => { + const container = new Container(); + const sym = Symbol("test.signUp"); + const ctx = makeCtx(); + const wrappedNoAudit = withSpan( + ctx.tracer, + { name: "test.signUp", op: "use-case" }, + withCapture(ctx.logger, { feature: "test" }, async (x: number) => x + 1), + ); + container.bind(sym).toConstantValue(wrappedNoAudit); + + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signUp: { + mutates: true, + audits: ["user.created"], + publishes: [], + consumes: [], + }, + }, + realtimeChannels: [], + jobs: [], + } as const); + + expect(() => + assertFeatureConformance(container, manifest, { signUp: sym }, ctx), + ).toThrow(/__audited/); + }); + + it("passes for a mutating use case with empty audits (no __audited required)", () => { + const container = new Container(); + const sym = Symbol("test.signUp"); + const ctx = makeCtx(); + const wrappedNoAudit = withSpan( + ctx.tracer, + { name: "test.signUp", op: "use-case" }, + withCapture(ctx.logger, { feature: "test" }, async (x: number) => x + 1), + ); + container.bind(sym).toConstantValue(wrappedNoAudit); + + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signUp: { + mutates: true, + audits: [], + publishes: [], + consumes: [], + }, + }, + realtimeChannels: [], + jobs: [], + } as const); + + expect(() => + assertFeatureConformance(container, manifest, { signUp: sym }, ctx), + ).not.toThrow(); + }); + + it("throws when no symbol is provided for a manifest use case", () => { + const container = new Container(); + const ctx = makeCtx(); + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signIn: { mutates: false, audits: [], publishes: [], consumes: [] }, + }, + realtimeChannels: [], + jobs: [], + } as const); + expect(() => assertFeatureConformance(container, manifest, {}, ctx)).toThrow( + /no symbol provided/, + ); + }); + + it("throws when the container cannot resolve the symbol", () => { + const container = new Container(); + const sym = Symbol("test.signIn"); + const ctx = makeCtx(); + const manifest = defineFeature({ + name: "test", + requiredCores: [], + useCases: { + signIn: { mutates: false, audits: [], publishes: [], consumes: [] }, + }, + realtimeChannels: [], + jobs: [], + } as const); + expect(() => + assertFeatureConformance(container, manifest, { signIn: sym }, ctx), + ).toThrow(ConformanceError); + }); +}); diff --git a/packages/core-shared/src/conformance/assert-bindings.ts b/packages/core-shared/src/conformance/assert-bindings.ts new file mode 100644 index 0000000..28fd7f7 --- /dev/null +++ b/packages/core-shared/src/conformance/assert-bindings.ts @@ -0,0 +1,62 @@ +import type { Container } from "inversify"; +import type { FeatureManifest } from "./define-feature"; +import { isInstrumented, isCaptured, isAudited } from "./brand-runtime"; +import { ConformanceError } from "./conformance-error"; +import type { BindContext } from "../di/bind-context"; + +/** + * Runtime check that every manifest-declared use case is bound through the + * brand-attaching wrappers (`withSpan` → `__instrumented`, + * `withCapture` → `__captured`, `withAudit` → `__audited` when required). + * + * Called at the tail of each feature's `bindProductionX(ctx)` so: + * - `pnpm dev` refuses to boot on drift (synchronous throw) + * - The check runs once per feature, not per request + * - Future apps that wire `bindProductionX` inherit the check for free + * + * The `symbols` map is declared inline by the feature's binder; the manifest + * holds the contract, the binder holds the container symbols. This keeps + * the manifest free of DI-coupling while letting each feature declare its + * own wiring keys. + */ +export function assertFeatureConformance( + container: Container, + manifest: FeatureManifest, + symbols: Record, + _ctx: BindContext, +): void { + void _ctx; // future: also check ctx.bus / ctx.auditLog presence vs requiredCores + for (const [name, useCase] of Object.entries(manifest.useCases)) { + const sym = symbols[name]; + if (!sym) { + throw new ConformanceError( + `${manifest.name}.${name}: no symbol provided in symbols map`, + ); + } + let bound: unknown; + try { + bound = container.get(sym); + } catch (cause) { + throw new ConformanceError( + `${manifest.name}.${name}: container could not resolve symbol (${String(cause)})`, + ); + } + if (!isInstrumented(bound)) { + throw new ConformanceError( + `${manifest.name}.${name}: missing __instrumented brand — was withSpan applied at bind time?`, + ); + } + if (!isCaptured(bound)) { + throw new ConformanceError( + `${manifest.name}.${name}: missing __captured brand — was withCapture applied at bind time?`, + ); + } + if (useCase.mutates && useCase.audits.length > 0) { + if (!isAudited(bound)) { + throw new ConformanceError( + `${manifest.name}.${name}: declares audits but binding is missing __audited brand — was withAudit applied at bind time?`, + ); + } + } + } +} diff --git a/packages/core-shared/src/conformance/brand-runtime.test.ts b/packages/core-shared/src/conformance/brand-runtime.test.ts new file mode 100644 index 0000000..f106b8f --- /dev/null +++ b/packages/core-shared/src/conformance/brand-runtime.test.ts @@ -0,0 +1,71 @@ +import { describe, it, expect } from "vitest"; +import { + attachBrand, + isInstrumented, + isCaptured, + isAudited, +} from "@/conformance/brand-runtime"; + +describe("brand-runtime", () => { + it("attachBrand adds a non-enumerable property and returns the same reference", () => { + const fn = () => {}; + const result = attachBrand(fn, "__instrumented"); + expect(result).toBe(fn); + expect(isInstrumented(fn)).toBe(true); + // Non-enumerable: must not show up in Object.keys + expect(Object.keys(fn)).not.toContain("__instrumented"); + }); + + it("predicates return false for unwrapped functions", () => { + const fn = () => {}; + expect(isInstrumented(fn)).toBe(false); + expect(isCaptured(fn)).toBe(false); + expect(isAudited(fn)).toBe(false); + }); + + it("predicates discriminate between brands", () => { + const instrumented = () => {}; + attachBrand(instrumented, "__instrumented"); + expect(isInstrumented(instrumented)).toBe(true); + expect(isCaptured(instrumented)).toBe(false); + expect(isAudited(instrumented)).toBe(false); + + const captured = () => {}; + attachBrand(captured, "__captured"); + expect(isInstrumented(captured)).toBe(false); + expect(isCaptured(captured)).toBe(true); + expect(isAudited(captured)).toBe(false); + + const audited = () => {}; + attachBrand(audited, "__audited"); + expect(isAudited(audited)).toBe(true); + }); + + it("composing brands stacks them on the same function", () => { + const fn = () => {}; + attachBrand(fn, "__instrumented"); + attachBrand(fn, "__captured"); + attachBrand(fn, "__audited"); + expect(isInstrumented(fn)).toBe(true); + expect(isCaptured(fn)).toBe(true); + expect(isAudited(fn)).toBe(true); + }); + + it("attached brands are non-writable and non-configurable", () => { + const fn = () => {}; + attachBrand(fn, "__instrumented"); + const desc = Object.getOwnPropertyDescriptor(fn, "__instrumented"); + expect(desc?.writable).toBe(false); + expect(desc?.configurable).toBe(false); + expect(desc?.enumerable).toBe(false); + expect(desc?.value).toBe(true); + }); + + it("predicates return false for non-function inputs", () => { + expect(isInstrumented(null)).toBe(false); + expect(isInstrumented(undefined)).toBe(false); + expect(isInstrumented(42)).toBe(false); + expect(isInstrumented("string")).toBe(false); + expect(isInstrumented({})).toBe(false); + }); +}); diff --git a/packages/core-shared/src/conformance/brand-runtime.ts b/packages/core-shared/src/conformance/brand-runtime.ts new file mode 100644 index 0000000..c378fe5 --- /dev/null +++ b/packages/core-shared/src/conformance/brand-runtime.ts @@ -0,0 +1,53 @@ +/** + * Runtime brand attachment + predicates. The companion to the phantom-type + * brands defined in `./brands.ts`: at compile time the brand is a structural + * intersection; at runtime it is a non-enumerable, non-writable, + * non-configurable property with the same name. + * + * Why non-enumerable: a wrapped function should not leak the marker through + * `Object.keys`, `JSON.stringify`, `for…in`, or spread. The marker only + * shows up to explicit lookups via `Reflect.has` or direct property access. + * + * Why non-writable + non-configurable: the marker is meant to be permanent + * once attached. The wrapper is the only caller; the marker is a one-shot + * commitment, not a mutable flag. + */ + +type Brand = "__instrumented" | "__captured" | "__audited"; + +/** + * Attaches the brand as a non-enumerable property on the given function. + * Returns the same reference (no allocation). Calling twice with the same + * brand on the same fn is a no-op (matching descriptors) — the engine silently + * accepts a redundant `defineProperty` call when every descriptor attribute + * matches the existing one. Redefining with different attributes (e.g. flipping + * `configurable`) would throw, but wrappers never do that. + */ +export function attachBrand(fn: F, brand: Brand): F { + Object.defineProperty(fn, brand, { + value: true, + enumerable: false, + writable: false, + configurable: false, + }); + return fn; +} + +function hasBrand(fn: unknown, brand: Brand): boolean { + if (typeof fn !== "function" && (typeof fn !== "object" || fn === null)) { + return false; + } + return (fn as Record)[brand] === true; +} + +export function isInstrumented(fn: unknown): boolean { + return hasBrand(fn, "__instrumented"); +} + +export function isCaptured(fn: unknown): boolean { + return hasBrand(fn, "__captured"); +} + +export function isAudited(fn: unknown): boolean { + return hasBrand(fn, "__audited"); +} diff --git a/packages/core-shared/src/conformance/brands.ts b/packages/core-shared/src/conformance/brands.ts index eeb1045..4ff9fe3 100644 --- a/packages/core-shared/src/conformance/brands.ts +++ b/packages/core-shared/src/conformance/brands.ts @@ -1,9 +1,11 @@ /** * 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. + * and `withAudit`. The brand has a type-level form (this file) and a + * non-enumerable runtime counterpart (see `./brand-runtime.ts`). The runtime + * cost is one `Object.defineProperty` call per wrap. 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 & { readonly __instrumented: true }; export type Captured = F & { readonly __captured: true }; diff --git a/packages/core-shared/src/conformance/conformance-error.test.ts b/packages/core-shared/src/conformance/conformance-error.test.ts new file mode 100644 index 0000000..4d4eb46 --- /dev/null +++ b/packages/core-shared/src/conformance/conformance-error.test.ts @@ -0,0 +1,17 @@ +import { describe, it, expect } from "vitest"; +import { ConformanceError } from "@/conformance/conformance-error"; + +describe("ConformanceError", () => { + it("extends Error with the standard shape", () => { + const err = new ConformanceError("auth.signIn: missing __instrumented brand"); + expect(err).toBeInstanceOf(Error); + expect(err).toBeInstanceOf(ConformanceError); + expect(err.message).toBe("auth.signIn: missing __instrumented brand"); + expect(err.name).toBe("ConformanceError"); + }); + + it("preserves a stack trace", () => { + const err = new ConformanceError("test"); + expect(typeof err.stack).toBe("string"); + }); +}); diff --git a/packages/core-shared/src/conformance/conformance-error.ts b/packages/core-shared/src/conformance/conformance-error.ts new file mode 100644 index 0000000..4683262 --- /dev/null +++ b/packages/core-shared/src/conformance/conformance-error.ts @@ -0,0 +1,13 @@ +/** + * Thrown by `assertFeatureConformance` when a binding does not match the + * manifest's declared shape. The boot assertion lets this propagate + * synchronously so `pnpm dev` refuses to start on drift. + */ +export class ConformanceError extends Error { + constructor(message: string) { + super(message); + this.name = "ConformanceError"; + // Maintain a proper prototype chain across down-compilation. + Object.setPrototypeOf(this, ConformanceError.prototype); + } +} diff --git a/packages/core-shared/src/conformance/index.ts b/packages/core-shared/src/conformance/index.ts index 773dc64..13bcf94 100644 --- a/packages/core-shared/src/conformance/index.ts +++ b/packages/core-shared/src/conformance/index.ts @@ -2,3 +2,11 @@ export type { Instrumented, Captured } from "./brands"; export type { FeatureManifest, UseCaseManifest } from "./define-feature"; export { defineFeature } from "./define-feature"; export type { ProductionUseCase } from "./production-use-case"; +export { + attachBrand, + isInstrumented, + isCaptured, + isAudited, +} from "./brand-runtime"; +export { ConformanceError } from "./conformance-error"; +export { assertFeatureConformance } from "./assert-bindings"; diff --git a/packages/core-shared/src/instrumentation/with-capture.test.ts b/packages/core-shared/src/instrumentation/with-capture.test.ts index 28b4803..179534f 100644 --- a/packages/core-shared/src/instrumentation/with-capture.test.ts +++ b/packages/core-shared/src/instrumentation/with-capture.test.ts @@ -3,6 +3,7 @@ import { withCapture } from "@/instrumentation/with-capture"; import type { ILogger } from "@/instrumentation/logger.interface"; import { isReported } from "@/instrumentation/reported-flag"; import type { Captured } from "@/conformance/brands"; +import { isCaptured } from "@/conformance/brand-runtime"; function makeLogger(): ILogger & { captureException: ReturnType } { return { @@ -70,3 +71,13 @@ describe("withCapture — brand", () => { expectTypeOf(wrapped).toMatchTypeOf>(); }); }); + +describe("withCapture — runtime brand", () => { + it("attaches __captured as a non-enumerable property on the wrapped function", async () => { + const logger = makeLogger(); + const fn = async (a: number) => a + 1; + const wrapped = withCapture(logger, { layer: "use-case" }, fn); + expect(isCaptured(wrapped)).toBe(true); + expect(Object.keys(wrapped)).not.toContain("__captured"); + }); +}); diff --git a/packages/core-shared/src/instrumentation/with-capture.ts b/packages/core-shared/src/instrumentation/with-capture.ts index ed17420..8652115 100644 --- a/packages/core-shared/src/instrumentation/with-capture.ts +++ b/packages/core-shared/src/instrumentation/with-capture.ts @@ -1,5 +1,6 @@ import type { ILogger } from "./logger.interface"; import type { Captured } from "../conformance/brands"; +import { attachBrand } from "../conformance/brand-runtime"; import { isReported, markReported } from "./reported-flag"; /** @@ -27,6 +28,8 @@ export function withCapture( tags: Record, fn: (...args: Args) => Promise, ): Captured<(...args: Args) => Promise> { + const PROPAGATED_BRANDS = ["__instrumented", "__audited"] as const; + const wrapped: (...args: Args) => Promise = async (...args) => { try { return await fn(...args); @@ -38,5 +41,14 @@ export function withCapture( throw err; } }; + // Propagate brands from the inner function (e.g. __audited from withAudit, + // __instrumented if already spanned) so the outermost binding carries all brands. + // __captured is omitted here because it is attached explicitly below. + for (const brand of PROPAGATED_BRANDS) { + if ((fn as unknown as Record)[brand] === true) { + attachBrand(wrapped, brand); + } + } + attachBrand(wrapped, "__captured"); return wrapped as Captured<(...args: Args) => Promise>; } diff --git a/packages/core-shared/src/instrumentation/with-span.test.ts b/packages/core-shared/src/instrumentation/with-span.test.ts index 91ccac4..1667cbd 100644 --- a/packages/core-shared/src/instrumentation/with-span.test.ts +++ b/packages/core-shared/src/instrumentation/with-span.test.ts @@ -2,6 +2,7 @@ import { describe, it, expect, expectTypeOf, vi } from "vitest"; import { withSpan } from "@/instrumentation/with-span"; import type { ITracer, ISpan, SpanOpts } from "@/instrumentation/tracer.interface"; import type { Instrumented } from "@/conformance/brands"; +import { isInstrumented } from "@/conformance/brand-runtime"; function makeRecordingTracer() { const calls: SpanOpts[] = []; @@ -70,3 +71,13 @@ describe("withSpan — brand", () => { expectTypeOf(wrapped).toMatchTypeOf>(); }); }); + +describe("withSpan — runtime brand", () => { + it("attaches __instrumented as a non-enumerable property on the wrapped function", async () => { + const { tracer } = makeRecordingTracer(); + const fn = async (a: number) => a + 1; + const wrapped = withSpan(tracer, { name: "test.brand", op: "use-case" }, fn); + expect(isInstrumented(wrapped)).toBe(true); + expect(Object.keys(wrapped)).not.toContain("__instrumented"); + }); +}); diff --git a/packages/core-shared/src/instrumentation/with-span.ts b/packages/core-shared/src/instrumentation/with-span.ts index 0685b0c..1e00da1 100644 --- a/packages/core-shared/src/instrumentation/with-span.ts +++ b/packages/core-shared/src/instrumentation/with-span.ts @@ -1,5 +1,8 @@ import type { ITracer, SpanOpts } from "./tracer.interface"; import type { Instrumented } from "../conformance/brands"; +import { attachBrand } from "../conformance/brand-runtime"; + +const PROPAGATED_BRANDS = ["__captured", "__audited"] as const; export function withSpan( tracer: ITracer, @@ -20,7 +23,17 @@ export function withSpan( 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. + attachBrand(wrapped, "__instrumented"); + // Propagate brands from the inner function (e.g. __captured from withCapture, + // __audited from withAudit) so the outermost binding carries all brands. + // withSpan is always outermost — the assertFeatureConformance check reads the + // container-resolved value (the withSpan result), so brands must be visible here. + for (const brand of PROPAGATED_BRANDS) { + if ((fn as unknown as Record)[brand] === true) { + attachBrand(wrapped, brand); + } + } + // Cast is the type-level concession — the brand is now also a non-enumerable + // runtime property attached above by `attachBrand`. return wrapped as Instrumented<(...args: Args) => Promise>; }