---
title: Local history API
description: Generated public TypeScript reference for @relkit/observability-local.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [inspector](/docs/modules/operations/inspector).

## Public imports

- `@relkit/observability-local` — 27 exports
- `@relkit/observability-local/worker` — 4 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                          | Kind  | Import from                                                         | Example                                                                                                                           |
| -------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [duckdbDatabaseLayer](/docs/api/observability-local#duckdbdatabaselayer)                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdatabaselayer)                                                                  |
| [DuckdbDatabaseService](/docs/api/observability-local#duckdbdatabaseservice-class)           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdatabaseservice-class)                                                          |
| [duckdbDriverLayer](/docs/api/observability-local#duckdbdriverlayer)                         | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdriverlayer)                                                                    |
| [DuckdbDriverService](/docs/api/observability-local#duckdbdriverservice-class)               | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdriverservice-class)                                                            |
| [duckdbError](/docs/api/observability-local#duckdberror)                                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdberror)                                                                          |
| [DuckdbError](/docs/api/observability-local#duckdberror-class)                               | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdberror-class)                                                                    |
| [duckdbWorkerLayer](/docs/api/observability-local#duckdbworkerlayer)                         | Value | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-effect.test.ts#L45) |
| [DuckdbWorkerService](/docs/api/observability-local#duckdbworkerservice-class)               | Value | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-effect.test.ts#L41) |
| [LocalLogOrigin](/docs/api/observability-local#locallogorigin-type-alias)                    | Type  | `@relkit/observability-local`                                       | [Module example](/docs/modules/operations/inspector)                                                                              |
| [LocalRecord](/docs/api/observability-local#localrecord-interface)                           | Type  | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localrecord-interface)                                                                |
| [LocalRecordValidationError](/docs/api/observability-local#localrecordvalidationerror-class) | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localrecordvalidationerror-class)                                                     |
| [LocalWorkerCommand](/docs/api/observability-local#localworkercommand-type-alias)            | Type  | `@relkit/observability-local`, `@relkit/observability-local/worker` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker.test.ts#L28)        |
| [LocalWorkerEffects](/docs/api/observability-local#localworkereffects-interface)             | Type  | `@relkit/observability-local`, `@relkit/observability-local/worker` | [API example](/docs/api/observability-local#localworkereffects-interface)                                                         |
| [LocalWorkerError](/docs/api/observability-local#localworkererror-class)                     | Value | `@relkit/observability-local`, `@relkit/observability-local/worker` | [API example](/docs/api/observability-local#localworkererror-class)                                                               |
| [localWorkerLayer](/docs/api/observability-local#localworkerlayer)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localworkerlayer)                                                                     |
| [LocalWorkerResponse](/docs/api/observability-local#localworkerresponse-interface)           | Type  | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker.test.ts#L12)        |
| [LocalWorkerService](/docs/api/observability-local#localworkerservice-class)                 | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localworkerservice-class)                                                             |
| [makeDuckdbWorkerEffect](/docs/api/observability-local#makeduckdbworkereffect)               | Value | `@relkit/observability-local`                                       | [Module example](/docs/modules/operations/inspector)                                                                              |
| [openDuckdbDatabase](/docs/api/observability-local#openduckdbdatabase)                       | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#openduckdbdatabase)                                                                   |
| [openDuckdbDatabaseEffect](/docs/api/observability-local#openduckdbdatabaseeffect)           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#openduckdbdatabaseeffect)                                                             |
| [recordTime](/docs/api/observability-local#recordtime)                                       | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#recordtime)                                                                           |
| [recordTimeEffect](/docs/api/observability-local#recordtimeeffect)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#recordtimeeffect)                                                                     |
| [startLocalWorker](/docs/api/observability-local#startlocalworker)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#startlocalworker)                                                                     |
| [startLocalWorkerEffect](/docs/api/observability-local#startlocalworkereffect)               | Value | `@relkit/observability-local`, `@relkit/observability-local/worker` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/history-shutdown-bun.test.ts#L20)           |
| [StoredLocalRecord](/docs/api/observability-local#storedlocalrecord-type-alias)              | Type  | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/import-history.test.ts#L33)       |
| [validateLocalRecord](/docs/api/observability-local#validatelocalrecord)                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#validatelocalrecord)                                                                  |
| [validateLocalRecordEffect](/docs/api/observability-local#validatelocalrecordeffect)         | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#validatelocalrecordeffect)                                                            |

## `index.ts`

Optional native history API; importing this package explicitly selects local storage.

### "./local/duckdb-database-effect.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-database-effect.js" module.

**Signature**

```ts
export * from "./local/duckdb-database-effect.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L3)

### "./local/duckdb-database.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-database.js" module.

**Signature**

```ts
export * from "./local/duckdb-database.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L4)

### "./local/duckdb-driver.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-driver.js" module.

**Signature**

```ts
export * from "./local/duckdb-driver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L5)

### "./local/duckdb-error.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-error.js" module.

**Signature**

```ts
export * from "./local/duckdb-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L6)

### "./local/duckdb-worker-effect.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-worker-effect.js" module.

**Signature**

```ts
export * from "./local/duckdb-worker-effect.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L7)

### "./local/worker-client.js" (namespace export)

Re-exports all named exports from the "./local/worker-client.js" module.

**Signature**

```ts
export * from "./local/worker-client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L2)

### "@relkit/observability/local/record" (namespace export)

Re-exports all named exports from the "@relkit/observability/local/record" module.

**Signature**

```ts
export * from "@relkit/observability/local/record";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L8)

## `duckdb-database-effect.ts`

Owns duckdb database effect for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbDatabaseService (class)

Database operations provided for one owned Effect Scope.

**Example**

```ts
const database = yield * DuckdbDatabaseService;
yield * database.flush();
```

**Signature**

```ts
declare class DuckdbDatabaseService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L27)

### duckdbDatabaseLayer

Provides a scoped database service using an injectable DuckdbDriverService.

**Example**

```ts
const program = Effect.gen(function* () {
  return yield* DuckdbDatabaseService;
});
const layer = duckdbDatabaseLayer(root);
```

**Signature**

```ts
declare const duckdbDatabaseLayer: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Layer.Layer<DuckdbDatabaseService, DuckdbError, DuckdbDriverService>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L95)

### openDuckdbDatabaseEffect

Acquires an instance and connection in the caller's Scope, initializes schema,
and returns Effect operations. Scope finalizers close the connection first,
then the instance, including on setup failure or interruption.

**Example**

```ts
const database = yield * openDuckdbDatabaseEffect(root);
yield * database.flush();
```

**Signature**

```ts
declare const openDuckdbDatabaseEffect: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy | undefined,
  redaction?: RedactionPolicy | undefined,
) => Effect.Effect<
  {
    imported: { records: number; malformed: number };
    append: (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>;
    configure: (
      retention: TelemetryLocalRetentionPolicy,
      redaction?: RedactionPolicy,
    ) => Effect.Effect<void, DuckdbError>;
    flush: () => Effect.Effect<void, DuckdbError>;
    list: (
      kind: "logs" | "requests" | "traces",
      input?: ObservabilityQueryRequest | undefined,
    ) => Effect.Effect<
      ObservabilityQueryPage<StoredLocalRecord>,
      DuckdbError | DuckdbQueryError,
      never
    >;
    detail: (
      kind: "request" | "log" | "trace",
      id: string,
    ) => Effect.Effect<
      | {
          log: StoredLocalRecord;
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          request: RequestRecord;
          spans: readonly SpanRecord[];
          roots: readonly SpanNode[];
          continuations: readonly { readonly traceId: string; readonly active: boolean }[];
          records: readonly ObservabilityRecord[];
          counts: {
            readonly records: number;
            readonly spans: number;
            readonly continuations: number;
          };
          incomplete: readonly string[];
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          trace: StoredLocalRecord | undefined;
          spans: Array<SpanRecord>;
          records: ReadonlyArray<StoredLocalRecord>;
          items: ReadonlyArray<StoredLocalRecord>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | undefined,
      DuckdbError | DuckdbQueryError,
      never
    >;
  },
  DuckdbError,
  Scope | DuckdbDriverService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L46)

## `duckdb-database.ts`

Owns duckdb database for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### openDuckdbDatabase

Opens a private DuckDB database and owns its Effect Scope until close.
The scoped Effect implementation contains acquisition and operation logic.

**Throws**

If acquisition, storage, or import fails.

**Example**

```ts
const database = await openDuckdbDatabase(root);
await database.close();
```

**Signature**

```ts
declare const openDuckdbDatabase: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Promise<{
  imported: { records: number; malformed: number };
  append: (
    records: Parameters<
      (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>
    >[0],
  ) => Promise<Array<StoredLocalRecord>>;
  list: (
    kind: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    input?: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[1],
  ) => Promise<ObservabilityQueryPage<StoredLocalRecord>>;
  detail: (
    kind: Parameters<
      (
        kind: "request" | "log" | "trace",
        id: string,
      ) => Effect.Effect<
        | {
            log: StoredLocalRecord;
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            request: RequestRecord;
            spans: readonly SpanRecord[];
            roots: readonly SpanNode[];
            continuations: readonly { readonly traceId: string; readonly active: boolean }[];
            records: readonly ObservabilityRecord[];
            counts: {
              readonly records: number;
              readonly spans: number;
              readonly continuations: number;
            };
            incomplete: readonly string[];
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            trace: StoredLocalRecord | undefined;
            spans: Array<SpanRecord>;
            records: ReadonlyArray<StoredLocalRecord>;
            items: ReadonlyArray<StoredLocalRecord>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | undefined,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    id: string,
  ) => Promise<
    | {
        log: StoredLocalRecord;
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        request: RequestRecord;
        spans: readonly SpanRecord[];
        roots: readonly SpanNode[];
        continuations: readonly { readonly traceId: string; readonly active: boolean }[];
        records: readonly ObservabilityRecord[];
        counts: {
          readonly records: number;
          readonly spans: number;
          readonly continuations: number;
        };
        incomplete: readonly string[];
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        trace: StoredLocalRecord | undefined;
        spans: Array<SpanRecord>;
        records: ReadonlyArray<StoredLocalRecord>;
        items: ReadonlyArray<StoredLocalRecord>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | undefined
  >;
  configure: (
    value: TelemetryLocalRetentionPolicy,
    nextRedaction?: RedactionPolicy,
  ) => Promise<void>;
  flush: () => Promise<void>;
  close: () => Promise<void>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database.ts#L27)

## `duckdb-driver.ts`

Owns duckdb driver for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbDriverService (class)

Injectable native DuckDB instance factory.

**Example**

```ts
const driver = yield * DuckdbDriverService;
const instance = yield * driver.create(path);
```

**Signature**

```ts
declare class DuckdbDriverService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-driver.ts#L17)

### duckdbDriverLayer

Live native driver for local observability storage.

**Example**

```ts
const database = yield * openDuckdbDatabaseEffect(root).pipe(Effect.provide(duckdbDriverLayer));
```

**Signature**

```ts
declare const duckdbDriverLayer: Layer.Layer<DuckdbDriverService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-driver.ts#L38)

## `duckdb-error.ts`

Owns duckdb error for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbError (class)

Expected local DuckDB IO or schema failure with a stable operation label.

**Example**

```ts
const failure = new DuckdbError({ operation: "connect", message: "failed", cause });
```

**Signature**

```ts
declare class DuckdbError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-error.ts#L14)

### duckdbError

Converts a native DuckDB failure to the local storage error channel.

**Example**

```ts
const error = duckdbError("connect", cause);
```

**Signature**

```ts
declare const duckdbError: <Cause>(operation: string, cause: Cause) => DuckdbError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-error.ts#L30)

## `duckdb-worker-effect.ts`

Composes serialized storage commands behind an injectable worker service.
Its scope owns the explicit database scope until close, failure or interruption.

### DuckdbWorkerService (class)

Injectable command executor whose owner must close its database.

**Signature**

```ts
declare class DuckdbWorkerService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L14)

### duckdbWorkerLayer

Owns the command service and releases native state on every scope exit.

**Signature**

```ts
declare const duckdbWorkerLayer: Layer.Layer<DuckdbWorkerService, never, DuckdbDriverService>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L43)

### makeDuckdbWorkerEffect

**Signature**

```ts
declare const makeDuckdbWorkerEffect: () => Effect.Effect<
  {
    execute: (
      command: LocalWorkerCommand,
    ) => Effect.Effect<
      | void
      | Array<StoredLocalRecord>
      | ObservabilityQueryPage<StoredLocalRecord>
      | { records: number; malformed: number },
      DuckdbError | DuckdbQueryError,
      never
    >;
    close: () => Effect.Effect<void, DuckdbError, never>;
  },
  never,
  DuckdbDriverService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L20)

## `duckdb-worker.ts`

Owns duckdb worker for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

## `worker-client-effect.ts`

Acquires the optional isolated Node worker and exposes shared structural effects.
Its caller owns close; neither record producers nor console logging import it.

### startLocalWorkerEffect

Starts one child without opening a database until the caller sends open.

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-effect.ts#L23)

## `worker-client-service.ts`

Owns worker client service for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### LocalWorkerService (class)

Injectable local worker operations. A Layer owns the worker process until
its scope closes, so callers can substitute a deterministic service in tests.

**Example**

```ts
const program = Effect.gen(function* () {
  const worker = yield* LocalWorkerService;
  return worker.pid;
});
```

**Signature**

```ts
declare class LocalWorkerService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-service.ts#L20)

### localWorkerLayer

Acquires a worker for the Layer scope and releases it on every exit.

**Example**

```ts
const result = await Effect.runPromise(program.pipe(Effect.provide(localWorkerLayer())));
```

**Signature**

```ts
declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer.Layer<LocalWorkerService, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-service.ts#L38)

## `worker-client.ts`

Owns worker client for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### LocalWorkerEffects

**Signature**

```ts
declare const LocalWorkerEffects: LocalWorkerEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L15)

### LocalWorkerError

**Signature**

```ts
declare const LocalWorkerError: typeof LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L12)

### LocalWorkerService

**Signature**

```ts
declare const LocalWorkerService: typeof LocalWorkerService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L14)

### localWorkerLayer

**Signature**

```ts
declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer<LocalWorkerService, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L14)

### startLocalWorker

Starts a local worker with the existing Promise API.

**Throws**

If process creation fails.

**Example**

```ts
const worker = startLocalWorker();
try {
  await worker.call({ type: "flush" });
} finally {
  await worker.close();
}
```

**Signature**

```ts
declare const startLocalWorker: (onFailure?: (error: Error) => void) => {
  pid: number | undefined;
  call: <T>(command: LocalWorkerCommand) => Promise<T>;
  close: () => Promise<void>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L30)

### startLocalWorkerEffect

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L13)

## `worker.ts`

Exposes IPC transport without evaluating the native DuckDB driver in its caller.
The isolated Node worker imports that driver in its own process. Its caller
retains the transport's explicit close operation and physical child identity.

### LocalWorkerCommand

**Signature**

```ts
declare const LocalWorkerCommand: LocalWorkerCommand;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L14)

### LocalWorkerEffects

**Signature**

```ts
declare const LocalWorkerEffects: LocalWorkerEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L12)

### LocalWorkerError

**Signature**

```ts
declare const LocalWorkerError: LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L13)

### startLocalWorkerEffect

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L11)

## `types.ts`

Validates diagnostic transport envelopes before any queue, IPC, or storage boundary.

### "./types.types.js" (namespace export)

Re-exports all named exports from the "./types.types.js" module.

**Signature**

```ts
export * from "./types.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L6)

### LocalRecordValidationError (class)

Invalid local record envelope at the persistent storage boundary.

**Example**

```ts
Effect.runSync(
  validateLocalRecordEffect(null).pipe(
    Effect.catchTag("LocalRecordValidationError", (error) => Effect.succeed(error.reason)),
  ),
);
```

**Signature**

```ts
declare class LocalRecordValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L16)

### recordTime

Synchronous compatibility adapter for local record time parsing.

**Example**

```ts
recordTime(logRecord);
```

**Signature**

```ts
declare const recordTime: (record: ObservabilityRecord) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L135)

### recordTimeEffect

Reads the canonical time field for a local record.

**Example**

```ts
Effect.runSync(recordTimeEffect(logRecord));
```

**Signature**

```ts
declare const recordTimeEffect: (
  record: ObservabilityRecord,
) => Effect.Effect<number, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L96)

### validateLocalRecord

Synchronous compatibility adapter for local record validation.

**Throws**

If the envelope or record is invalid.

**Example**

```ts
validateLocalRecord(envelope);
```

**Signature**

```ts
declare const validateLocalRecord: <Input>(value: Input) => asserts value is Input & LocalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L115)

### validateLocalRecordEffect

Validates a local transport envelope before persistence.

**Example**

```ts
Effect.runSync(validateLocalRecordEffect(envelope));
```

**Signature**

```ts
declare const validateLocalRecordEffect: <Input>(
  value: Input,
) => Effect.Effect<Input & LocalRecord, LocalRecordValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L54)

## `types.types.ts`

Redacted telemetry envelopes and the diagnostic worker IPC protocol; no storage resources.

### LocalLogOrigin (type alias)

A stable origin assigned to local telemetry records.

**Signature**

```ts
type LocalLogOrigin = "application" | "relkit" | "inspector";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L10)

### LocalRecord (interface)

Transport envelope accepted by the local worker.

**Example**

```ts
const envelope: LocalRecord = { key: "source:1", origin: "application", record };
```

**Signature**

```ts
export interface LocalRecord {
  readonly key: string;
  readonly origin: LocalLogOrigin;
  readonly record: ObservabilityRecord;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L18)

### LocalWorkerCommand (type alias)

Commands sent through the local worker IPC channel.

**Signature**

```ts
type LocalWorkerCommand =
  | {
      readonly type: "open";
      readonly root: string;
      readonly retention?: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "append"; readonly records: readonly LocalRecord[] }
  | {
      readonly type: "query";
      readonly kind: "logs" | "requests" | "traces";
      readonly query: ObservabilityQueryRequest;
    }
  | { readonly type: "detail"; readonly kind: "log" | "request" | "trace"; readonly id: string }
  | {
      readonly type: "retention";
      readonly retention: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "flush" | "close" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L31)

### LocalWorkerResponse (interface)

A worker reply carrying a value or a safe error code and message.

**Signature**

```ts
export interface LocalWorkerResponse {
  readonly id: number;
  readonly fatal?: boolean;
  readonly value?: Schema.Json;
  readonly error?: string;
  readonly code?: ObservabilityQueryError["code"];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L53)

### StoredLocalRecord (type alias)

A persisted model record with its local cursor and origin.

**Signature**

```ts
type StoredLocalRecord = ObservabilityRecord & {
  readonly cursor: string;
  readonly origin: LocalLogOrigin;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L25)

## `worker-client-error.ts`

Typed IPC failures shared with tooling; no worker or database is acquired here.

### LocalWorkerError (class)

A local worker creation, IPC, timeout, or response failure.

**Example**

```ts
Effect.runPromise(
  worker
    .call(command)
    .pipe(Effect.catchTag("LocalWorkerError", (error) => Effect.succeed(error.reason))),
);
```

**Signature**

```ts
declare class LocalWorkerError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L13)

### WorkerTransportError (class)

Failure raised by the IPC transport before mapping to the Effect channel.

**Signature**

```ts
declare class WorkerTransportError { constructor(
    readonly reason: "send" | "timeout" | "response",
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L25)

### workerFailure

Maps an IPC failure to a tagged worker error without losing query codes.

**Signature**

```ts
declare const workerFailure: <Failure>(
  error: Failure,
  reason: LocalWorkerError["reason"],
) => LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L35)

## `worker-client.types.ts`

Structural worker authority borrowed by telemetry producers without native dependencies.

### LocalWorkerEffects (interface)

Effect operations for a live local telemetry worker process.
The owning Layer or caller must close the worker after its final call.

**Example**

```ts
const worker = Effect.runSync(startLocalWorkerEffect());
await Effect.runPromise(worker.close());
```

**Signature**

```ts
export interface LocalWorkerEffects {
  readonly pid: number | undefined;
  /** @param command - Worker IPC command. @returns Its response or a tagged worker error. */
  readonly call: (
    command: LocalWorkerCommand,
  ) => Effect.Effect<Schema.Json | undefined, LocalWorkerError>;
  /** @returns Completion after the worker process and pending calls are released. */
  readonly close: () => Effect.Effect<void, LocalWorkerError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client.types.ts#L14)