apcore-js 0.19.0 → 0.21.0

package/dist/middleware/tracing.js

@@ -0,0 +1,89 @@
+/**
+ * TracingMiddleware — OpenTelemetry-compatible span lifecycle management (Issue #42).
+ *
+ * Behaviour:
+ *   - before(): creates a span named after the module_id, sets apcore.* attributes,
+ *               and stores the span_id in context.data["_apcore.mw.tracing.span_id"].
+ *   - after():  ends the span with status OK.
+ *   - onError(): ends the span with status ERROR.
+ *   - If @opentelemetry/api is not installed (and no tracer is injected), all methods
+ *     are silent no-ops.
+ */
+import { createRequire } from 'node:module';
+import { Middleware } from './base.js';
+export const CTX_TRACING_SPAN_ID = '_apcore.mw.tracing.span_id';
+// Internal key — stores the live Span object for retrieval in after()/onError().
+// Not part of the public spec; not serialised; prefixed with _ to signal internal use.
+const CTX_TRACING_SPAN = '_apcore.mw.tracing._active_span';
+// OTel SpanStatusCode values (from @opentelemetry/api):
+//   UNSET = 0, OK = 1, ERROR = 2
+const SPAN_STATUS_OK = 1;
+const SPAN_STATUS_ERROR = 2;
+// Attempt to load @opentelemetry/api synchronously via Node.js require.
+// If the package is absent, _defaultTrace remains null and TracingMiddleware
+// silently becomes a no-op unless a tracer is explicitly injected.
+const _nodeRequire = createRequire(import.meta.url);
+let _defaultTrace = null;
+try {
+    _defaultTrace = _nodeRequire('@opentelemetry/api').trace;
+}
+catch {
+    _defaultTrace = null;
+}
+export class TracingMiddleware extends Middleware {
+    _tracer;
+    constructor(options = {}) {
+        super(options.priority ?? 800);
+        if ('tracer' in options) {
+            this._tracer = options.tracer ?? null;
+        }
+        else {
+            const name = options.serviceName ?? 'apcore';
+            this._tracer = _defaultTrace ? _defaultTrace.getTracer(name) : null;
+        }
+    }
+    /** Type-safe accessor for the active span stored by before(). */
+    _activeSpan(context) {
+        const val = context.data[CTX_TRACING_SPAN];
+        if (val == null)
+            return null;
+        // Minimal shape check: any valid OtelSpan must expose an `end` method.
+        if (typeof val === 'object' && typeof val.end === 'function') {
+            return val;
+        }
+        return null;
+    }
+    before(moduleId, _inputs, context) {
+        if (!this._tracer)
+            return null;
+        try {
+            const span = this._tracer.startSpan(moduleId);
+            span.setAttribute('apcore.trace_id', context.traceId);
+            span.setAttribute('apcore.caller_id', context.callerId ?? '');
+            span.setAttribute('apcore.module_id', moduleId);
+            context.data[CTX_TRACING_SPAN_ID] = span.spanContext().spanId;
+            context.data[CTX_TRACING_SPAN] = span;
+        }
+        catch (err) {
+            console.warn(`[apcore:middleware] TracingMiddleware: span creation failed for '${moduleId}':`, err);
+        }
+        return null;
+    }
+    after(_moduleId, _inputs, _output, context) {
+        const span = this._activeSpan(context);
+        if (span) {
+            span.setStatus({ code: SPAN_STATUS_OK });
+            span.end();
+        }
+        return null;
+    }
+    onError(_moduleId, _inputs, error, context) {
+        const span = this._activeSpan(context);
+        if (span) {
+            span.setStatus({ code: SPAN_STATUS_ERROR, message: String(error) });
+            span.end();
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=tracing.js.map

package/dist/middleware/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/middleware/tracing.ts"],"names":[],"mappings":"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"}

package/dist/module.d.ts

@@ -1,7 +1,7 @@
 /**
  * Module interface and related data types.
  */
-import type { TSchema } from '@sinclair/typebox';
+import { type TSchema } from '@sinclair/typebox';
 import type { Context } from './context.js';
 export interface ModuleAnnotations {
     readonly readonly: boolean;
@@ -20,6 +20,19 @@ export interface ModuleAnnotations {
     readonly paginated: boolean;
     /** Pagination strategy. Accepts any string. */
     readonly paginationStyle: string;
+    /**
+     * Whether the module appears in enumeration surfaces (`Registry.list()`,
+     * `Registry.find()`, manifest export, MCP `tools/list`). Defaults to `true`
+     * so existing modules remain visible. Setting `false` keeps the module
+     * callable by exact ID but hides it from discovery — `ephemeral.*` modules
+     * SHOULD set this to `false` per PROTOCOL_SPEC §4.4 / RFC
+     * `apcore/docs/spec/rfc-ephemeral-modules.md`.
+     *
+     * Optional on the interface so v0.20.x callers building `ModuleAnnotations`
+     * literals keep compiling; absent values default to `true` per spec when
+     * `Registry._isDiscoverable` interprets them.
+     */
+    readonly discoverable?: boolean;
     /** Extension dictionary for ecosystem package metadata. */
     readonly extra: Readonly<Record<string, unknown>>;
 }
@@ -65,8 +78,74 @@ export interface PreflightResult {
     readonly checks: PreflightCheckResult[];
     readonly requiresApproval: boolean;
     readonly errors: Array<Record<string, unknown>>;
+    /**
+     * Optional. Module-self-reported structured prediction of the changes that
+     * executing the call would produce, populated by `Executor.validate()` when
+     * the target module implements `preview()` (see RFC
+     * `apcore/docs/spec/rfc-preview-method.md`, currently Draft / RFC).
+     *
+     * - Absent (or empty) when the module does not implement `preview()` or
+     *   when `preview()` returned `null`.
+     * - When `preview()` throws, `predictedChanges` is left unset and a
+     *   `module_preview` advisory check carries the warning, mirroring
+     *   `preflight()` semantics (warnings do not fail validation).
+     */
+    readonly predictedChanges?: Change[];
 }
-export declare function createPreflightResult(checks: PreflightCheckResult[], requiresApproval?: boolean): PreflightResult;
+export declare function createPreflightResult(checks: PreflightCheckResult[], requiresApproval?: boolean, predictedChanges?: Change[]): PreflightResult;
+/**
+ * Structured prediction of a single side-effect that executing a module call
+ * would produce. Per RFC `apcore/docs/spec/rfc-preview-method.md`
+ * (Draft / RFC, target acceptance v0.21.0).
+ *
+ * `action`, `target`, and `summary` are required; module authors define their
+ * own free-form taxonomy for `action` (e.g. "write", "delete", "send",
+ * "charge", "publish") and `target` (e.g. "users.42", "smtp:user@example.com").
+ *
+ * `before` / `after` are optional snapshots of prior / predicted state. Both
+ * are typed `unknown` to keep the schema heterogeneous across module classes
+ * (DB writes, network calls, file I/O, email sends).
+ *
+ * Extension fields with the `x-` prefix are permitted (consistent with
+ * PROTOCOL_SPEC §4.4 extras).
+ */
+export interface Change {
+    /** Free-form verb describing the kind of change (e.g. "write", "delete", "send"). */
+    action: string;
+    /** Free-form identifier of what is changed (e.g. "users.42", "stripe:charge:ch_abc"). */
+    target: string;
+    /** Required, human-readable single-line summary of the change. */
+    summary: string;
+    /** Optional. Snapshot of the prior state, when observable. */
+    before?: unknown;
+    /** Optional. Predicted new state. */
+    after?: unknown;
+    /** Extension fields. Keys MUST start with the `x-` prefix. */
+    [key: `x-${string}`]: unknown;
+}
+/**
+ * Module's structured prediction of the changes that calling `execute()` with
+ * the given inputs would produce. Returned by the optional `Module.preview()`
+ * method; folded into `PreflightResult.predictedChanges` by
+ * `Executor.validate()`.
+ */
+export interface PreviewResult {
+    /** Ordered list of predicted side-effects. */
+    changes: Change[];
+}
+/**
+ * TypeBox schema mirroring `Change`. Exported alongside the TypeScript type
+ * for runtime validation / wire-format use. Mirrors the JSON Schema sketch in
+ * `apcore/docs/spec/rfc-preview-method.md`. The raw JSON Schema body
+ * (`type`, `required`, `properties`, `patternProperties`,
+ * `additionalProperties: false`) is the canonical cross-SDK wire format; the
+ * `[Kind]` field routes `Value.Check` to the registered checker above.
+ */
+export declare const TChange: import("@sinclair/typebox").TUnsafe<Change>;
+/** TypeBox schema mirroring `PreviewResult`. */
+export declare const TPreviewResult: import("@sinclair/typebox").TObject<{
+    changes: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnsafe<Change>>;
+}>;
 export interface Module {
     inputSchema: TSchema;
     outputSchema: TSchema;
@@ -78,6 +157,19 @@ export interface Module {
     validate?(inputs: Record<string, unknown>): ValidationResult | Promise<ValidationResult>;
     /** Optional: Domain-specific pre-execution warnings (called by Executor.validate() Check 7). Advisory only — warnings do NOT block execution. */
     preflight?(inputs: Record<string, unknown>, context: Context): string[] | Promise<string[]>;
+    /**
+     * Optional: Return a structured prediction of the changes this call would
+     * produce. Invoked by `Executor.validate()` after the standard validation
+     * pipeline succeeds, only on modules that implement it.
+     *
+     * Per RFC `apcore/docs/spec/rfc-preview-method.md` (currently Draft / RFC):
+     * - MUST NOT have side effects.
+     * - Returning `null` (or omitting the method) means "no predicted changes".
+     * - Throwing / rejecting is treated as advisory and does NOT fail validation.
+     *   The error is surfaced as a warning via the `module_preview` check,
+     *   matching `preflight()` semantics.
+     */
+    preview?(inputs: Record<string, unknown>, context: Context): PreviewResult | null | Promise<PreviewResult | null>;
     /** Optional: Return module description for LLM/AI tool discovery. */
     describe?(): ModuleDescription | Promise<ModuleDescription>;
     /** Optional: Called when module is loaded into the registry. */

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAQ,KAAK,OAAO,EAAsB,MAAM,mBAAmB,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAClD,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,mBAAmB,EAAE,iBAchC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACrC,iBAAiB,CAYnB;AAQD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CA+BpF;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,EAAE,EAC9B,gBAAgB,GAAE,OAAe,EACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAC1B,eAAe,CASjB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,MAAM;IACrB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,CAAC,GAAG,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA0CD;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,6CA8BlB,CAAC;AAEH,gDAAgD;AAChD,eAAO,MAAM,cAAc;;EAKzB,CAAC;AAEH,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvH,qDAAqD;IACrD,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpG,2DAA2D;IAC3D,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzF,iJAAiJ;IACjJ,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,CACN,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,OAAO,GACf,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACxD,qEAAqE;IACrE,QAAQ,CAAC,IAAI,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5D,gEAAgE;IAChE,MAAM,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,4FAA4F;IAC5F,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7C,uDAAuD;IACvD,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;CACpC"}

package/dist/module.js

@@ -1,6 +1,7 @@
 /**
  * Module interface and related data types.
  */
+import { Kind, Type, TypeRegistry } from '@sinclair/typebox';
 export const DEFAULT_ANNOTATIONS = Object.freeze({
     readonly: false,
     destructive: false,
@@ -13,6 +14,7 @@ export const DEFAULT_ANNOTATIONS = Object.freeze({
     cacheKeyFields: null,
     paginated: false,
     paginationStyle: 'cursor',
+    discoverable: true,
     extra: Object.freeze({}),
 });
 /**
@@ -35,7 +37,7 @@ export function createAnnotations(overrides) {
 const KNOWN_WIRE_KEYS = new Set([
     'readonly', 'destructive', 'idempotent', 'requires_approval',
     'open_world', 'streaming', 'cacheable', 'cache_ttl',
-    'cache_key_fields', 'paginated', 'pagination_style', 'extra',
+    'cache_key_fields', 'paginated', 'pagination_style', 'discoverable', 'extra',
 ]);
 /**
  * Serialize ModuleAnnotations to a snake_case JSON-compatible record.
@@ -53,6 +55,7 @@ export function annotationsToJSON(a) {
         cache_key_fields: a.cacheKeyFields,
         paginated: a.paginated,
         pagination_style: a.paginationStyle,
+        discoverable: a.discoverable,
         extra: a.extra,
     };
 }
@@ -90,15 +93,109 @@ export function annotationsFromJSON(data) {
         cacheKeyFields: data['cache_key_fields'] ?? null,
         paginated: data['paginated'] ?? false,
         paginationStyle: data['pagination_style'] ?? 'cursor',
+        // PROTOCOL_SPEC §4.4 — defaults to true so wires from older SDKs that
+        // don't yet emit the field stay backward-compatible.
+        discoverable: data['discoverable'] ?? true,
         // §4.4.1 rule 7: nested explicit `extra` wins over legacy top-level overflow.
         extra: Object.freeze({ ...overflow, ...explicitExtra }),
     });
 }
-export function createPreflightResult(checks, requiresApproval = false) {
+export function createPreflightResult(checks, requiresApproval = false, predictedChanges) {
     const valid = checks.every(c => c.passed);
     const errors = checks
         .filter(c => !c.passed && c.error != null)
         .map(c => c.error);
+    if (predictedChanges !== undefined) {
+        return { valid, checks, requiresApproval, errors, predictedChanges };
+    }
     return { valid, checks, requiresApproval, errors };
 }
+/**
+ * Custom TypeBox kind for `Change`.
+ *
+ * Encoded via `Type.Unsafe<Change>(...)` so the underlying JSON Schema can
+ * carry both `patternProperties: { "^x-": {} }` (admitting arbitrary `x-*`
+ * extension keys per PROTOCOL_SPEC §4.4 / §4.6 conventions) and
+ * `additionalProperties: false` (rejecting unknown non-`x-` keys). TypeBox
+ * 0.34's `Type.Object` schema-checker does not consult `patternProperties`,
+ * so a `Type.Object({...}, { additionalProperties: false })` form would
+ * incorrectly reject `x-*` keys; and `Type.Intersect([Object, Record])`
+ * loses `additionalProperties: false` precision. The cross-SDK
+ * schema-encoding table in `apcore/docs/spec/rfc-preview-method.md`
+ * ("Change.x-* extension fields") prescribes the `Type.Unsafe` escape hatch.
+ *
+ * To make the schema usable with `Value.Check` (which routes by `[Kind]`), we
+ * register a custom `'apcore:Change'` kind whose checker enforces the same
+ * shape the JSON Schema describes. The JSON Schema body remains the canonical
+ * cross-SDK wire form.
+ */
+const CHANGE_KIND = 'apcore:Change';
+if (!TypeRegistry.Has(CHANGE_KIND)) {
+    TypeRegistry.Set(CHANGE_KIND, (_schema, value) => {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return false;
+        }
+        const v = value;
+        if (typeof v.action !== 'string')
+            return false;
+        if (typeof v.target !== 'string')
+            return false;
+        if (typeof v.summary !== 'string')
+            return false;
+        const known = new Set(['action', 'target', 'summary', 'before', 'after']);
+        for (const key of Object.keys(v)) {
+            if (known.has(key))
+                continue;
+            // Anything else MUST start with `x-` (any value).
+            if (!key.startsWith('x-'))
+                return false;
+        }
+        return true;
+    });
+}
+/**
+ * TypeBox schema mirroring `Change`. Exported alongside the TypeScript type
+ * for runtime validation / wire-format use. Mirrors the JSON Schema sketch in
+ * `apcore/docs/spec/rfc-preview-method.md`. The raw JSON Schema body
+ * (`type`, `required`, `properties`, `patternProperties`,
+ * `additionalProperties: false`) is the canonical cross-SDK wire format; the
+ * `[Kind]` field routes `Value.Check` to the registered checker above.
+ */
+export const TChange = Type.Unsafe({
+    [Kind]: CHANGE_KIND,
+    type: 'object',
+    required: ['action', 'target', 'summary'],
+    properties: {
+        action: {
+            type: 'string',
+            description: 'Free-form verb describing the kind of change.',
+        },
+        target: {
+            type: 'string',
+            description: 'Free-form identifier of what is changed.',
+        },
+        summary: {
+            type: 'string',
+            description: 'Required, human-readable single-line summary of the change.',
+        },
+        before: {
+            // unknown — module-class specific. JSON Schema `{}` accepts any value.
+            description: 'Optional. Snapshot of the prior state, when observable.',
+        },
+        after: {
+            description: 'Optional. Predicted new state.',
+        },
+    },
+    patternProperties: {
+        // Arbitrary x-* extension keys with arbitrary values (PROTOCOL_SPEC §4.4).
+        '^x-': {},
+    },
+    additionalProperties: false,
+});
+/** TypeBox schema mirroring `PreviewResult`. */
+export const TPreviewResult = Type.Object({
+    changes: Type.Array(TChange, {
+        description: "Module's prediction of what would change if the call were executed.",
+    }),
+});
 //# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -1 +1 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAgB,IAAI,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAqC3E,MAAM,CAAC,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAClE,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,CAAC;IACX,cAAc,EAAE,IAAI;IACpB,SAAS,EAAE,KAAK;IAChB,eAAe,EAAE,QAAQ;IACzB,YAAY,EAAE,IAAI;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;CACzB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAsC;IAEtC,IAAI,QAAQ,GAAG,SAAS,EAAE,QAAQ,IAAI,mBAAmB,CAAC,QAAQ,CAAC;IACnE,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,iCAAiC,QAAQ,6BAA6B,CAAC,CAAC;QACrF,QAAQ,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,mBAAmB;QACtB,GAAG,SAAS;QACZ,QAAQ;QACR,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC9B,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB;IAC5D,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW;IACnD,kBAAkB,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,OAAO;CAC7E,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAoB;IACpD,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,iBAAiB,EAAE,CAAC,CAAC,gBAAgB;QACrC,UAAU,EAAE,CAAC,CAAC,SAAS;QACvB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,SAAS,EAAE,CAAC,CAAC,QAAQ;QACrB,gBAAgB,EAAE,CAAC,CAAC,cAAc;QAClC,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,gBAAgB,EAAE,CAAC,CAAC,eAAe;QACnC,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,KAAK,EAAE,CAAC,CAAC,KAAK;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,aAAa,GAAI,IAAI,CAAC,OAAO,CAA6B,IAAI,EAAE,CAAC;IACvE,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,QAAQ,GAAI,IAAI,CAAC,WAAW,CAAY,IAAI,CAAC,CAAC;IAClD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,OAAO,CAAC,IAAI,CAAC,kCAAkC,QAAQ,6BAA6B,CAAC,CAAC;QACtF,QAAQ,GAAG,CAAC,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAG,IAAI,CAAC,UAAU,CAAa,IAAI,KAAK;QAChD,WAAW,EAAG,IAAI,CAAC,aAAa,CAAa,IAAI,KAAK;QACtD,UAAU,EAAG,IAAI,CAAC,YAAY,CAAa,IAAI,KAAK;QACpD,gBAAgB,EAAG,IAAI,CAAC,mBAAmB,CAAa,IAAI,KAAK;QACjE,SAAS,EAAG,IAAI,CAAC,YAAY,CAAa,IAAI,IAAI;QAClD,SAAS,EAAG,IAAI,CAAC,WAAW,CAAa,IAAI,KAAK;QAClD,SAAS,EAAG,IAAI,CAAC,WAAW,CAAa,IAAI,KAAK;QAClD,QAAQ;QACR,cAAc,EAAG,IAAI,CAAC,kBAAkB,CAAqB,IAAI,IAAI;QACrE,SAAS,EAAG,IAAI,CAAC,WAAW,CAAa,IAAI,KAAK;QAClD,eAAe,EAAG,IAAI,CAAC,kBAAkB,CAAY,IAAI,QAAQ;QACjE,sEAAsE;QACtE,qDAAqD;QACrD,YAAY,EAAG,IAAI,CAAC,cAAc,CAAyB,IAAI,IAAI;QACnE,8EAA8E;QAC9E,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,aAAa,EAAE,CAAC;KACxD,CAAC,CAAC;AACL,CAAC;AAyCD,MAAM,UAAU,qBAAqB,CACnC,MAA8B,EAC9B,mBAA4B,KAAK,EACjC,gBAA2B;IAE3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC;SACzC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAM,CAAC,CAAC;IACtB,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACvE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;AACrD,CAAC;AA4CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,GAAG,eAAe,CAAC;AAEpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;IACnC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,KAAK,EAAW,EAAE;QACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC/C,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC/C,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAChD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;QAC1E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;YACjC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC7B,kDAAkD;YAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAS;IACzC,CAAC,IAAI,CAAC,EAAE,WAAW;IACnB,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC;IACzC,UAAU,EAAE;QACV,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,+CAA+C;SAC7D;QACD,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,0CAA0C;SACxD;QACD,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,6DAA6D;SAC3E;QACD,MAAM,EAAE;YACN,uEAAuE;YACvE,WAAW,EAAE,yDAAyD;SACvE;QACD,KAAK,EAAE;YACL,WAAW,EAAE,gCAAgC;SAC9C;KACF;IACD,iBAAiB,EAAE;QACjB,2EAA2E;QAC3E,KAAK,EAAE,EAAE;KACV;IACD,oBAAoB,EAAE,KAAK;CAC5B,CAAC,CAAC;AAEH,gDAAgD;AAChD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE;QAC3B,WAAW,EACT,qEAAqE;KACxE,CAAC;CACH,CAAC,CAAC"}

package/dist/observability/batch-span-processor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Span processors: SimpleSpanProcessor (synchronous) and BatchSpanProcessor (async, non-blocking).
+ */
+import type { Span, SpanExporter } from './tracing.js';
+export interface SpanProcessor {
+    onSpan(span: Span): void;
+    shutdown(): Promise<void>;
+}
+/** Synchronous processor — exports each span immediately. For development and testing. */
+export declare class SimpleSpanProcessor implements SpanProcessor {
+    private readonly _exporter;
+    constructor(options: {
+        exporter: SpanExporter;
+    });
+    onSpan(span: Span): void;
+    shutdown(): Promise<void>;
+}
+export interface BatchSpanProcessorOptions {
+    exporter: SpanExporter;
+    maxQueueSize?: number;
+    scheduleDelayMs?: number;
+    maxExportBatchSize?: number;
+    exportTimeoutMs?: number;
+}
+/**
+ * Non-blocking batch processor — buffers spans and exports in background.
+ *
+ * When the queue is full, new spans are dropped and spansDropped is incremented.
+ * On shutdown, remaining spans are flushed within exportTimeoutMs.
+ */
+export declare class BatchSpanProcessor implements SpanProcessor {
+    private readonly _exporter;
+    private readonly _maxQueueSize;
+    private readonly _scheduleDelayMs;
+    private readonly _maxExportBatchSize;
+    private readonly _exportTimeoutMs;
+    private _queue;
+    private _spansDropped;
+    private _timer;
+    constructor(options: BatchSpanProcessorOptions);
+    get queueSize(): number;
+    get spansDropped(): number;
+    onSpan(span: Span): void;
+    shutdown(): Promise<void>;
+    private _startTimer;
+    private _flush;
+}
+//# sourceMappingURL=batch-span-processor.d.ts.map

package/dist/observability/batch-span-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-span-processor.d.ts","sourceRoot":"","sources":["../../src/observability/batch-span-processor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,0FAA0F;AAC1F,qBAAa,mBAAoB,YAAW,aAAa;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE;QAAE,QAAQ,EAAE,YAAY,CAAA;KAAE;IAI/C,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAIlB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,YAAY,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,YAAW,aAAa;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,MAAM,CAA+C;gBAEjD,OAAO,EAAE,yBAAyB;IAS9C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAQlB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B,OAAO,CAAC,WAAW;YAUL,MAAM;CAQrB"}

package/dist/observability/batch-span-processor.js

@@ -0,0 +1,89 @@
+/**
+ * Span processors: SimpleSpanProcessor (synchronous) and BatchSpanProcessor (async, non-blocking).
+ */
+/** Synchronous processor — exports each span immediately. For development and testing. */
+export class SimpleSpanProcessor {
+    _exporter;
+    constructor(options) {
+        this._exporter = options.exporter;
+    }
+    onSpan(span) {
+        this._exporter.export(span);
+    }
+    async shutdown() { }
+}
+/**
+ * Non-blocking batch processor — buffers spans and exports in background.
+ *
+ * When the queue is full, new spans are dropped and spansDropped is incremented.
+ * On shutdown, remaining spans are flushed within exportTimeoutMs.
+ */
+export class BatchSpanProcessor {
+    _exporter;
+    _maxQueueSize;
+    _scheduleDelayMs;
+    _maxExportBatchSize;
+    _exportTimeoutMs;
+    _queue = [];
+    _spansDropped = 0;
+    _timer = null;
+    constructor(options) {
+        this._exporter = options.exporter;
+        this._maxQueueSize = options.maxQueueSize ?? 2048;
+        this._scheduleDelayMs = options.scheduleDelayMs ?? 5000;
+        this._maxExportBatchSize = options.maxExportBatchSize ?? 512;
+        this._exportTimeoutMs = options.exportTimeoutMs ?? 30000;
+        this._startTimer();
+    }
+    get queueSize() {
+        return this._queue.length;
+    }
+    get spansDropped() {
+        return this._spansDropped;
+    }
+    onSpan(span) {
+        if (this._queue.length >= this._maxQueueSize) {
+            this._spansDropped++;
+            return;
+        }
+        this._queue.push(span);
+    }
+    async shutdown() {
+        if (this._timer !== null) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+        let timeoutId = null;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('Export timeout')), this._exportTimeoutMs);
+        });
+        try {
+            await Promise.race([this._flush(), timeoutPromise]);
+        }
+        catch {
+            this._queue = [];
+        }
+        finally {
+            if (timeoutId !== null)
+                clearTimeout(timeoutId);
+        }
+    }
+    _startTimer() {
+        this._timer = setInterval(() => {
+            void this._flush();
+        }, this._scheduleDelayMs);
+        // Prevent the timer from keeping the Node.js event loop alive in tests
+        if (typeof this._timer.unref === 'function') {
+            this._timer.unref();
+        }
+    }
+    async _flush() {
+        while (this._queue.length > 0) {
+            const batch = this._queue.splice(0, this._maxExportBatchSize);
+            for (const span of batch) {
+                this._exporter.export(span);
+            }
+        }
+    }
+}
+//# sourceMappingURL=batch-span-processor.js.map

package/dist/observability/batch-span-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-span-processor.js","sourceRoot":"","sources":["../../src/observability/batch-span-processor.ts"],"names":[],"mappings":"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"}

package/dist/observability/context-logger.d.ts

@@ -1,8 +1,59 @@
 /**
- * Structured logging: ContextLogger and ObsLoggingMiddleware.
+ * Structured logging: ContextLogger, RedactionConfig, and ObsLoggingMiddleware.
  */
+import type { Config } from '../config.js';
 import type { Context } from '../context.js';
 import { Middleware } from '../middleware/base.js';
+/**
+ * Default sensitive field patterns (Issue #45 §3 — canonical superset
+ * promoted from #43 §5). Used when no `redaction.sensitive_keys`
+ * (canonical) / `redaction.field_patterns` (legacy) is configured.
+ * Wildcards follow apcore's `matchPattern` semantics (segment-aware globs).
+ *
+ * Aligned with apcore-python's authoritative list (Python is the canonical
+ * superset because broader default redaction is safer than narrower).
+ * `apiKey` is kept alongside `api_key` / `apikey` for camelCase parity
+ * because TypeScript's `matchPattern` is case-sensitive.
+ */
+export declare const DEFAULT_REDACTION_FIELD_PATTERNS: readonly string[];
+/**
+ * Runtime-configurable redaction rules for ObsLoggingMiddleware.
+ * Applied in addition to schema-level x-sensitive annotations.
+ */
+export declare class RedactionConfig {
+    readonly fieldPatterns: readonly string[];
+    readonly valuePatterns: readonly (RegExp | string)[];
+    readonly replacement: string;
+    constructor(options?: {
+        fieldPatterns?: string[];
+        valuePatterns?: (RegExp | string)[];
+        replacement?: string;
+    });
+    /**
+     * Build a RedactionConfig from an apcore {@link Config}.
+     *
+     * Reads canonical keys first (sync finding CRITICAL #4 — aligns with
+     * apcore-python / apcore-rust):
+     *   - `obs.redaction.sensitive_keys` (string[])
+     *   - `obs.redaction.regex_patterns` (string[]; compiled case-insensitively)
+     *   - `obs.redaction.replacement`    (string)
+     *
+     * For backwards compatibility, falls back to legacy keys (Issue #43 §5)
+     * when the canonical key is unset, and emits a one-shot deprecation
+     * warning the first time a legacy key is read:
+     *   - `observability.redaction.field_patterns`   (legacy of sensitive_keys)
+     *   - `observability.redaction.value_patterns`   (legacy of regex_patterns)
+     *   - `observability.redaction.replacement`      (legacy of replacement)
+     *
+     * Falls back to {@link DEFAULT_REDACTION_FIELD_PATTERNS} when no sensitive
+     * keys are configured so `_secret_*` and standard sensitive keys (apiKey,
+     * api_key, token, authorization, password) remain redacted out of the box.
+     */
+    static fromConfig(config: Config): RedactionConfig;
+    /** Apply redaction rules to a flat object of field name → value. */
+    apply(obj: Record<string, unknown>): Record<string, unknown>;
+    private _shouldRedact;
+}
 interface WritableOutput {
     write(s: string): void;
 }
@@ -41,10 +92,12 @@ export declare class ObsLoggingMiddleware extends Middleware {
     private _logger;
     private _logInputs;
     private _logOutputs;
+    private _redactionConfig;
     constructor(options?: {
         logger?: ContextLogger;
         logInputs?: boolean;
         logOutputs?: boolean;
+        redactionConfig?: RedactionConfig | null;
     });
     before(moduleId: string, inputs: Record<string, unknown>, context: Context): null;
     after(moduleId: string, _inputs: Record<string, unknown>, output: Record<string, unknown>, context: Context): null;

package/dist/observability/context-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-logger.d.ts","sourceRoot":"","sources":["../../src/observability/context-logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAyBnD,UAAU,cAAc;IACtB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,OAAO,CAAC,EAAE;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;KACzB;IAUD,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACpE,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;KACzB,GAAG,aAAa;IAQjB,OAAO,CAAC,KAAK;IAoCb,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAG9D;AAED,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,WAAW,CAAU;gBAEjB,OAAO,CAAC,EAAE;QACpB,MAAM,CAAC,EAAE,aAAa,CAAC;QACvB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB;IAOQ,MAAM,CACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,OAAO,GACf,IAAI;IAgBE,KAAK,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,OAAO,GACf,IAAI;IAqBE,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,OAAO,GACf,IAAI;CAcR"}
+{"version":3,"file":"context-logger.d.ts","sourceRoot":"","sources":["../../src/observability/context-logger.ts"],"names":[],"mappings":"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"}