brass-runtime 1.15.0 → 1.16.1

package/dist/tracer-Hwt1cl7h.d.ts

@@ -0,0 +1,189 @@
+import { R as RuntimeHooks, b as RingBufferOptions, c as RuntimeEvent, a as RuntimeEmitContext, d as RuntimeEventRecord, e as RuntimeSpanLink, T as TraceContext, B as Baggage } from './effect-DIUHZ9IN.js';
+import { R as RuntimeClock } from './schedule-CK3Ml_7p.js';
+
+type MetricType = "counter" | "gauge" | "histogram";
+type MetricValue = {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly value: number;
+    readonly labels: Record<string, string>;
+    readonly timestamp: number;
+};
+type HistogramBuckets = {
+    readonly boundaries: readonly number[];
+    counts: number[];
+    sum: number;
+    count: number;
+    min: number;
+    max: number;
+    exemplars?: Array<MetricExemplar | undefined>;
+};
+type MetricExemplar = {
+    readonly value: number;
+    readonly timestamp: number;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly labels?: Record<string, string>;
+};
+type MetricsRegistry = {
+    /** Create or get a counter. */
+    readonly counter: (name: string, labels?: Record<string, string>) => Counter;
+    /** Create or get a gauge. */
+    readonly gauge: (name: string, labels?: Record<string, string>) => Gauge;
+    /** Create or get a histogram. */
+    readonly histogram: (name: string, boundaries?: number[], labels?: Record<string, string>) => Histogram;
+    /** Get all current metric values. */
+    readonly snapshot: () => MetricSnapshot;
+    /** Reset all metrics. */
+    readonly reset: () => void;
+};
+type Counter = {
+    readonly increment: (n?: number) => void;
+    readonly value: () => number;
+};
+type Gauge = {
+    readonly set: (value: number) => void;
+    readonly increment: (n?: number) => void;
+    readonly decrement: (n?: number) => void;
+    readonly value: () => number;
+};
+type Histogram = {
+    readonly observe: (value: number, exemplar?: Omit<MetricExemplar, "value"> | MetricExemplar) => void;
+    readonly buckets: () => HistogramBuckets;
+    readonly percentile: (p: number) => number;
+};
+type MetricSnapshot = {
+    readonly counters: Array<{
+        name: string;
+        labels: Record<string, string>;
+        value: number;
+    }>;
+    readonly gauges: Array<{
+        name: string;
+        labels: Record<string, string>;
+        value: number;
+    }>;
+    readonly histograms: Array<{
+        name: string;
+        labels: Record<string, string>;
+        buckets: HistogramBuckets;
+    }>;
+};
+/**
+ * Creates a metrics registry.
+ *
+ * ```ts
+ * const metrics = makeMetrics();
+ *
+ * const requestCount = metrics.counter("http_requests_total", { method: "GET" });
+ * requestCount.increment();
+ *
+ * const latency = metrics.histogram("http_request_duration_ms");
+ * latency.observe(42.5);
+ *
+ * const activeConns = metrics.gauge("active_connections");
+ * activeConns.set(10);
+ *
+ * console.log(metrics.snapshot());
+ * ```
+ */
+declare function makeMetrics(): MetricsRegistry;
+
+type EventHandler = (ev: RuntimeEventRecord) => void;
+declare function runtimeHooksToEventHandler(hooks: RuntimeHooks): EventHandler;
+type EventBusOptions = RingBufferOptions;
+declare class EventBus implements RuntimeHooks {
+    private readonly options;
+    private seq;
+    private subs;
+    private flushScheduled;
+    private readonly boundFlush;
+    constructor(options?: EventBusOptions);
+    emit(ev: RuntimeEvent, ctx: RuntimeEmitContext): void;
+    subscribe(handler: EventHandler, perSubscriberCapacity?: number): () => void;
+    subscribeHooks(hooks: RuntimeHooks, perSubscriberCapacity?: number): () => void;
+    flush(budget?: number): void;
+}
+
+type RuntimeSpanEvent = {
+    wallTs: number;
+    name: string;
+    attrs?: unknown;
+};
+type RuntimeSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceState?: string;
+    name: string;
+    startWallTs: number;
+    endWallTs?: number;
+    attrs: Record<string, unknown>;
+    links: RuntimeSpanLink[];
+    events: RuntimeSpanEvent[];
+};
+type InMemoryTracerOptions = {
+    readonly sanitizeAttributes?: (attrs: Record<string, unknown>) => Record<string, unknown>;
+    readonly sanitizeError?: (error: unknown) => unknown;
+    readonly maxFinishedSpans?: number;
+    readonly maxSpanAgeMs?: number;
+    readonly clock?: () => number;
+};
+type InMemoryTracerStats = {
+    readonly storedSpans: number;
+    readonly finishedSpans: number;
+    readonly prunedFinishedSpans: number;
+};
+declare class InMemoryTracer implements RuntimeHooks {
+    private readonly options;
+    spans: Map<string, RuntimeSpan>;
+    private readonly finishedSpanIds;
+    private readonly finishedSpanSet;
+    private finishedSpanOffset;
+    private finishedSpanCount;
+    private prunedFinishedSpans;
+    constructor(options?: InMemoryTracerOptions);
+    emit(ev: RuntimeEvent, ctx: RuntimeEmitContext): void;
+    exportFinished(): RuntimeSpan[];
+    pruneFinished(spanIds?: Iterable<string>): number;
+    stats(): InMemoryTracerStats;
+    private attrs;
+    private error;
+    private now;
+    private pruneExpiredFinished;
+    private pruneFinishedOverLimit;
+    private markFinished;
+    private deleteFinished;
+    private peekOldestFinished;
+    private deleteOldestFinished;
+    private compactFinishedIds;
+}
+
+type TraceSamplingInput = {
+    readonly traceId: string;
+    readonly spanName?: string;
+    readonly parentSampled?: boolean;
+    readonly attributes?: Record<string, unknown>;
+};
+type TraceSampler = ((input: TraceSamplingInput) => boolean) | {
+    shouldSample(input: TraceSamplingInput): boolean;
+};
+interface Tracer {
+    newTraceId(): string;
+    newSpanId(): string;
+}
+declare const defaultTracer: Tracer;
+type BrassEnv = {
+    brass?: {
+        tracer?: Tracer;
+        traceSeed?: TraceContext;
+        baggage?: Baggage;
+        sampler?: TraceSampler;
+        respectRemoteSampled?: boolean;
+        forceSampleOnError?: boolean;
+        childName?: (parentName?: string) => string | undefined;
+        clock?: RuntimeClock;
+    };
+};
+
+export { type BrassEnv as B, type Counter as C, EventBus as E, type Gauge as G, type Histogram as H, InMemoryTracer as I, type MetricsRegistry as M, type RuntimeSpan as R, type TraceSampler as T, type MetricExemplar as a, type MetricSnapshot as b, type TraceSamplingInput as c, type Tracer as d, type InMemoryTracerOptions as e, type EventBusOptions as f, type EventHandler as g, type HistogramBuckets as h, type InMemoryTracerStats as i, type MetricType as j, type MetricValue as k, type RuntimeSpanEvent as l, defaultTracer as m, makeMetrics as n, runtimeHooksToEventHandler as r };

package/dist/tracing-DqbTKGcf.d.ts

@@ -0,0 +1,148 @@
+import { A as Async, E as Exit } from './effect-DIUHZ9IN.js';
+
+/**
+ * Acquires a resource, uses it, and guarantees release regardless of outcome.
+ *
+ * - `acquire` runs uninterruptibly (once started, it completes)
+ * - `use` runs with the acquired resource
+ * - `release` runs after `use` completes (success, failure, or interruption)
+ *
+ * ```ts
+ * const result = bracket(
+ *   openConnection(),                    // acquire
+ *   (conn) => queryDatabase(conn),       // use
+ *   (conn, exit) => conn.close()         // release (always runs)
+ * );
+ * ```
+ */
+declare function bracket<R, E, A, B>(acquire: Async<R, E, A>, use: (resource: A) => Async<R, E, B>, release: (resource: A, exit: Exit<E, B>) => Async<R, any, void>): Async<R, E, B>;
+/**
+ * Runs `effect` and then runs `finalizer` regardless of the outcome.
+ * The finalizer receives the exit value for inspection.
+ *
+ * ```ts
+ * const result = ensuring(
+ *   doWork(),
+ *   (exit) => logCompletion(exit)
+ * );
+ * ```
+ */
+declare function ensuring<R, E, A>(effect: Async<R, E, A>, finalizer: (exit: Exit<E, A>) => Async<R, any, void>): Async<R, E, A>;
+declare function resource<R, E, A>(acquire: Async<R, E, A>, release: (resource: A, exit: Exit<any, any>) => Async<R, any, void>): Resource<R, E, A>;
+declare const makeResource: typeof resource;
+declare function resourceSucceed<A>(value: A): Resource<unknown, never, A>;
+declare function resourceFromManaged<R, E, A>(m: Managed<R, E, A>): Resource<R, E, A>;
+declare function useResource<R, E, A, R2, E2, B>(res: Resource<R, E, A>, body: (resource: A) => Async<R2, E2, B>): Async<R & R2, E | E2, B>;
+declare function resourceAll<R, E, Resources extends readonly any[]>(resources: {
+    [K in keyof Resources]: Resource<R, E, Resources[K]>;
+}): Resource<R, E, Resources>;
+/**
+ * A Resource describes a scoped value. It is acquired for each `use`, released
+ * in LIFO order, and can be composed with `map`, `flatMap`, and `zip`.
+ */
+type Resource<R, E, A> = {
+    readonly _tag: "Resource";
+    readonly use: <R2, E2, B>(body: (resource: A) => Async<R2, E2, B>) => Async<R & R2, E | E2, B>;
+    readonly map: <B>(f: (resource: A) => B) => Resource<R, E, B>;
+    readonly flatMap: <R2, E2, B>(f: (resource: A) => Resource<R2, E2, B>) => Resource<R & R2, E | E2, B>;
+    readonly zip: <R2, E2, B>(that: Resource<R2, E2, B>) => Resource<R & R2, E | E2, [A, B]>;
+};
+declare const Resource: Readonly<{
+    make: typeof resource;
+    succeed: typeof resourceSucceed;
+    fromManaged: typeof resourceFromManaged;
+    all: typeof resourceAll;
+    use: typeof useResource;
+}>;
+/**
+ * A Managed resource describes how to acquire and release a resource.
+ * It can be used multiple times — each `use` call acquires a fresh instance.
+ *
+ * ```ts
+ * const dbPool = managed(
+ *   createPool({ max: 10 }),
+ *   (pool) => pool.close()
+ * );
+ *
+ * // Use it:
+ * const result = useManaged(dbPool, (pool) => pool.query("SELECT 1"));
+ * ```
+ */
+type Managed<R, E, A> = {
+    readonly _tag: "Managed";
+    readonly acquire: Async<R, E, A>;
+    readonly release: (resource: A, exit: Exit<any, any>) => Async<R, any, void>;
+};
+/**
+ * Creates a Managed resource descriptor.
+ */
+declare function managed<R, E, A>(acquire: Async<R, E, A>, release: (resource: A, exit?: Exit<any, any>) => Async<R, any, void>): Managed<R, E, A>;
+/**
+ * Uses a Managed resource: acquires, runs the body, and releases.
+ */
+declare function useManaged<R, E, A, B>(m: Managed<R, E, A>, body: (resource: A) => Async<R, E, B>): Async<R, E, B>;
+/**
+ * Combines multiple Managed resources. All are acquired in order,
+ * and released in reverse order (LIFO).
+ *
+ * ```ts
+ * const resources = managedAll([dbPool, cacheConn, fileHandle]);
+ * const result = useManaged(resources, ([db, cache, file]) => ...);
+ * ```
+ */
+declare function managedAll<R, E, Resources extends readonly any[]>(manageds: {
+    [K in keyof Resources]: Managed<R, E, Resources[K]>;
+}): Managed<R, E, Resources>;
+
+type SpanContext = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+};
+type SpanStatus = "ok" | "error" | "unset";
+type Span = {
+    readonly name: string;
+    readonly context: SpanContext;
+    readonly startTime: number;
+    endTime?: number;
+    status: SpanStatus;
+    readonly attributes: Record<string, string | number | boolean>;
+    readonly events: SpanEvent[];
+};
+type SpanEvent = {
+    readonly name: string;
+    readonly time: number;
+    readonly attributes?: Record<string, string | number | boolean>;
+};
+type TracerConfig = {
+    /** Service name for span metadata. */
+    readonly serviceName: string;
+    /** Called when a span ends (for export). */
+    readonly onSpanEnd?: (span: Span) => void;
+    /** Sampling rate (0.0 to 1.0). Default: 1.0 (sample everything). */
+    readonly sampleRate?: number;
+};
+type Tracer = {
+    /** Wrap an effect in a span. */
+    readonly span: <R, E, A>(name: string, effect: Async<R, E, A>, attributes?: Record<string, string | number | boolean>) => Async<R, E, A>;
+    /** Get all completed spans (for testing). */
+    readonly spans: () => readonly Span[];
+    /** Clear collected spans. */
+    readonly clear: () => void;
+};
+/**
+ * Creates a tracer that wraps effects in spans.
+ *
+ * ```ts
+ * const tracer = makeTracer({ serviceName: "my-app" });
+ *
+ * const result = await run(
+ *   tracer.span("fetchUser", fetchUser(id), { userId: id })
+ * );
+ *
+ * console.log(tracer.spans()); // all completed spans
+ * ```
+ */
+declare function makeTracer(config: TracerConfig): Tracer;
+
+export { type Managed as M, Resource as R, type Span as S, type Tracer as T, type SpanContext as a, type SpanEvent as b, type SpanStatus as c, type TracerConfig as d, bracket as e, ensuring as f, makeTracer as g, managed as h, managedAll as i, resourceAll as j, resourceFromManaged as k, resourceSucceed as l, makeResource as m, useResource as n, resource as r, useManaged as u };

package/docs/ARCHITECTURE.md

@@ -0,0 +1,292 @@
+# 🧱 ARCHITECTURE — brass-runtime
+
+This document explains the **architectural structure** of `brass-runtime`, how the layers relate to each other, and the design principles behind them.
+
+The architecture is intentionally inspired by **ZIO 2**, but implemented from scratch in **TypeScript**, without relying on `Promise` as the semantic runtime primitive.
+
+---
+
+## High-level overview
+
+```
+┌────────────────────────────────────────────┐
+│              User Programs                 │
+│  (examples, apps, libraries, tests)        │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│           High-level Modules                │
+│   (HTTP, Streams, Resources, etc.)          │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│        Core Effect Runtime                  │
+│  Async / Effect / Fiber / Scope / Scheduler │
+└────────────────────────────────────────────┘
+                ▲
+                │
+┌────────────────────────────────────────────┐
+│      JavaScript Host Environment            │
+│   (event loop, timers, fetch, callbacks)   │
+└────────────────────────────────────────────┘
+```
+
+Key idea:
+> **Only the core runtime knows about execution.**  
+> Everything else is *pure descriptions* interpreted by the runtime.
+
+---
+
+## Core principles
+
+### 1. No Promise-based semantics
+- `Promise` is never the semantic primitive.
+- Async work is represented explicitly as data (`Async`).
+- The runtime *interprets* async effects using callbacks and schedulers.
+
+This ensures:
+- Deterministic scheduling
+- Cooperative cancellation
+- Structured concurrency
+- Testability
+
+---
+
+### 2. Lazy by default
+All effects are **lazy**:
+- Nothing runs until interpreted by a `Fiber`
+- Creating an effect is pure and side-effect free
+
+```ts
+const eff = http.getJson<Post>("/posts/1")
+// nothing has happened yet
+```
+
+Execution only begins when:
+- Forked into a fiber
+- Or awaited via `toPromise` (interop helper)
+
+---
+
+### 3. Structured concurrency
+Fibers always belong to a **Scope**.
+
+Rules:
+- Child fibers cannot outlive their parent scope
+- Closing a scope interrupts all children
+- Finalizers run in LIFO order
+
+This prevents:
+- Leaked async tasks
+- Forgotten cleanups
+- Detached background work
+
+---
+
+## Core Runtime Layer
+
+### Main components
+
+```
+Async
+  │
+  ▼
+Fiber ── Scheduler
+  │
+  ▼
+Scope ── Finalizers
+```
+
+#### `Async<R, E, A>`
+- Algebraic data type representing effectful computation
+- Variants: `Succeed | Fail | Sync | Async | FlatMap`
+- Pure data, no execution
+
+#### `Fiber<E, A>`
+- Interpreter of `Async`
+- Owns:
+  - Stack
+  - RunState
+  - Interrupt status
+  - Finalizers
+- Can be:
+  - Joined
+  - Interrupted
+  - Forked
+
+#### `Scheduler`
+- Cooperative task queue
+- Ensures fairness
+- No preemption
+- Explicit scheduling boundaries
+
+#### `Scope`
+- Lifetime manager
+- Owns:
+  - Child fibers
+  - Sub-scopes
+  - Finalizers
+- Deterministic cleanup
+
+---
+
+## Streams Architecture
+
+Streams are **pull-based**, inspired by ZIO Streams.
+
+```
+ZStream
+   │
+   ▼
+ Pull<R, Option<E>, A>
+```
+
+### Characteristics
+- Backpressure-aware
+- Resource-safe
+- Scope-bound
+- Deterministic cleanup
+
+### Why pull-based?
+- Simpler cancellation semantics
+- Natural backpressure
+- Easier reasoning about lifetimes
+
+---
+
+## HTTP Module Architecture (brass-http)
+
+HTTP is **not part of the core runtime**.
+
+It is implemented as a **high-level module** built entirely on `Async`.
+
+```
+HttpRequest
+     │
+     ▼
+HttpClient (Request => Async)
+     │
+     ▼
+ Middlewares
+ (withMeta, logging, retries)
+     │
+     ▼
+ Content helpers
+ (getJson, getText)
+```
+
+### Important properties
+- Fully lazy
+- Cancelable via fiber interruption
+- Composable via middleware functions
+- Environment-aware (baseUrl, headers, auth)
+
+HTTP execution only happens when:
+- The returned `Async` is run by a fiber
+
+---
+
+## Middleware model
+
+Middlewares are pure functions:
+
+```ts
+type Middleware = (client: HttpClient) => HttpClient
+```
+
+They:
+- Do not execute effects
+- Only transform descriptions
+- Compose left-to-right
+
+Examples:
+- `withMeta`
+- logging
+- retries
+- tracing
+- auth injection
+
+---
+
+## Interop Layer
+
+### `toPromise`
+- Thin boundary for examples and DX
+- Not part of core semantics
+- Converts fiber execution into a `Promise`
+
+### `fromPromiseAbortable`
+- Adapts Promise APIs that support `AbortSignal`
+- Preserves cooperative cancellation
+- Integrates cleanly with fibers
+
+Interop is **explicit and contained**.
+
+---
+
+## What is NOT allowed
+
+By design:
+- ❌ Hidden Promises inside effects
+- ❌ Detached async work
+- ❌ Implicit background execution
+- ❌ Fire-and-forget APIs
+
+If something runs:
+> It must be owned by a fiber and a scope.
+
+---
+
+## Extension points
+
+Designed to grow horizontally:
+
+- New modules (HTTP, FS, DB, etc.)
+- New stream combinators
+- New schedulers (priority, test)
+- New runtimes (browser, workers)
+
+Without changing the core semantics.
+
+---
+
+## Mental model (TL;DR)
+
+- **Core** = execution + rules
+- **Async** = description
+- **Fiber** = interpreter
+- **Scope** = lifetime
+- **Modules** = pure libraries on top
+- **Interop** = explicit escape hatch
+
+If you understand this:
+👉 you understand the entire system.
+
+---
+
+## Status
+
+This architecture is:
+- Experimental
+- Intentionally minimal
+- Designed for learning, exploration, and correctness
+
+But:
+> It already enforces stronger guarantees than most Promise-based codebases.
+
+---
+
+MIT License © 2025
+
+
+---
+
+## Further reading
+
+- [Getting started](./getting-started.md)
+- [Modules overview](./modules.md)
+- [Cancellation & interruption](./cancellation.md)
+- [Observability (hooks & events)](./observability.md)
+- [HTTP client](./http.md)

package/docs/README.md

@@ -0,0 +1,63 @@
+# Documentation
+
+Start here:
+
+- **[Getting started](./getting-started.md)** — installation, first effects, and running examples
+- **[Architecture](./ARCHITECTURE.md)** — how the runtime is structured
+- **[Cancellation & interruption](./cancellation.md)** — interruption semantics, scopes, and cancellable `Async`
+- **[Observability](./observability.md)** — hooks, events, sinks, tracing, and HTTP policy context
+- **[HTTP client](./http.md)** — ZIO-style HTTP built on brass-runtime
+- **[HTTP recipes](./http-recipes.md)** — typed clients, custom transports, production adoption, observability, and config validation
+- **[Recipes](./recipes/README.md)** — copyable runtime, layer, HTTP server, testing, and performance paths
+- **[API polish notes](./api-polish.md)** — first-release DX audit and compatibility posture
+- **[First release checklist](./release.md)** — local release gate and perf evidence workflow
+- **[Modules overview](./modules.md)** — map of core modules and where things live
+- **[AI context pack](./ai/PROJECT_MAP.md)** — compact project map, invariants, validation matrix, and public API notes
+- **[Agent module boundaries](./agent-boundaries.md)** — rules for keeping `brass-agent` isolated from the core runtime
+- **[Brass Agent install and configure](./agent-install-and-configure.md)** — end-to-end local setup for CLI, config, providers, and VS Code
+
+- [Agent LLM adapters](./agent-llm-adapters.md)
+- [Agent env files](./agent-env-files.md)
+- [Agent global usage and workspace discovery](./agent-global-usage.md)
+- [Agent apply mode](./agent-apply-mode.md)
+- [Brass Agent CLI](./agent-cli.md)
+- [Agent init](./agent-init.md)
+- [Agent observability](./agent-observability.md)
+- [Agent approvals](./agent-approvals.md)
+- [Agent config and policy files](./agent-config.md)
+- [Agent project command discovery](./agent-project-commands.md)
+- [Agent project intelligence](./agent-project-intelligence.md)
+- [Declarative optimized planning roadmap](./agent-declarative-optimized-planning.md)
+- [Agent context discovery](./agent-context-discovery.md)
+- [Agent patch quality loop](./agent-patch-quality-loop.md)
+- [Agent automatic rollback safety](./agent-rollback-safety.md)
+- [Agent DX surfaces](./agent-dx.md)
+
+- [VS Code patch preview](./agent-vscode-patch-preview.md)
+- [VS Code enhanced diff preview](./agent-vscode-diff-preview.md)
+- [VS Code run history](./agent-vscode-run-history.md)
+- [VS Code batch runner](./agent-vscode-batch-runner.md)
+- [VS Code UX](./agent-vscode-ux.md)
+- [VS Code Project dashboard](./agent-vscode-project-dashboard.md)
+- [VS Code Chat layout / focus mode](./agent-vscode-chat-layout.md)
+- [Copilot-like VS Code DX](./agent-copilot-like-dx.md)
+- [Chat sessions and slash commands](./agent-chat-sessions.md)
+- [Agent follow-up context](./agent-follow-up-context.md)
+- [VS Code code actions](./agent-vscode-code-actions.md)
+- [VS Code problems-aware chat](./agent-vscode-problems.md)
+- [VS Code inline assist](./agent-vscode-inline-assist.md)
+- [Agent release readiness](./agent-release-readiness.md)
+- [VS Code local install](./agent-vscode-install.md)
+- [VS Code auto-discovery](./agent-vscode-auto-discovery.md)
+- [VS Code model setup](./agent-vscode-model-setup.md)
+- [Agent local install and doctor](./agent-local-install.md)
+- [Agent local tests](./agent-local-tests.md)
+
+- [Agent rollback patches](./agent-rollback.md)
+- [Agent redaction](./agent-redaction.md)
+- [Agent run artifacts](./agent-run-artifacts.md)
+- [Agent CI mode](./agent-ci.md)
+- [Agent presets](./agent-presets.md)
+- [Agent batch runs](./agent-batch.md)
+- [VS Code full clean and reinstall](./agent-vscode-clean-install.md)
+- [Agent language and workspace setup UX](agent-language-workspace-ux.md)