{
  "name": "@forge-sdk/telemetry",
  "language": "typescript",
  "version": "0.1.0",
  "description": "ANVIL telemetry contract: span collection, audit trails, and observability for the Forge SDK.",
  "manifest": "forge-ts/packages/forge-telemetry/package.json",
  "manifestSha256": "967e0717d6a121085fa156bcfa2940a9dcdd25fdb2d08b6de7c6329add6d006c",
  "status": "source-reference",
  "registryPublicationVerified": false,
  "route": "/libraries/typescript/telemetry",
  "features": {},
  "files": [
    {
      "path": "forge-ts/packages/forge-telemetry/src/audit.ts",
      "sha256": "ed674f25df1466fb9be1140c36e901abc88cf4c8f2a469ffbf7c4d75b9192a1b",
      "artifactSha256": "c1168667a28021788baed932ede7c98c3b17e3a1346ea46f12a2e8fe3a45e849",
      "url": "/reference/source/forge-ts/packages/forge-telemetry/src/audit.ts.txt",
      "declarations": [
        {
          "name": "AuditEntry",
          "line": 20,
          "signature": "export interface AuditEntry {\n  /** Sequential index in the trail (0-based). */\n  readonly index: number;\n  /** The audit event. */\n  readonly event: AuditEvent;\n}",
          "documentation": "A single audit trail entry.\n\nEach entry has a sequential index assigned by the AuditTrail and wraps\nan AuditEvent with the full event details."
        },
        {
          "name": "AuditTrail",
          "line": 48,
          "signature": "export class AuditTrail {\n  constructor(agentDid: string);\n  append(event: AuditEvent): void;\n  entries(): readonly AuditEntry[];\n  len(): number;\n  isEmpty(): boolean;\n  last(): AuditEntry | undefined;\n  agentDid(): string;\n  filterByKind(kind: AuditEventKindType): AuditEntry[];\n}",
          "documentation": "An append-only audit trail with optional Ed25519 signatures.\n\nPer ANVIL Spec section 14.2, every significant agent operation is recorded\nin the audit trail. Entries are timestamped and optionally signed by the\nagent's Ed25519 key. The trail assigns sequential indices starting from 0."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-telemetry/src/collector.ts",
      "sha256": "571cb2531cb02d67549971d165535c81cb20f88ba37e41801f4f80ddda1fc1fa",
      "artifactSha256": "327480f34a6a1e767d2b7710e66237118c29cc2817fa61f5b5d660a19a0e6f10",
      "url": "/reference/source/forge-ts/packages/forge-telemetry/src/collector.ts.txt",
      "declarations": [
        {
          "name": "CompletedSpan",
          "line": 23,
          "signature": "export interface CompletedSpan {\n  /** The unique identifier for this span. */\n  readonly spanId: SpanId;\n  /** The span name (e.g., \"anvil.generate\", \"anvil.tool.invoke\"). */\n  readonly name: string;\n  /** Key-value attributes associated with this span. */\n  readonly attributes: ReadonlyArray<readonly [string, string]>;\n  /** ISO 8601 timestamp of when the span was started. */\n  readonly startTime: string;\n  /** ISO 8601 timestamp of when the span was ended. */\n  readonly endTime: string;\n  /** The agent's OAS DID, if available. */\n  readonly agentDid: string | undefined;\n}",
          "documentation": "A completed span with timing information.\n\nRepresents a span that has been started and ended, capturing the full\nduration and attributes of the operation."
        },
        {
          "name": "SpanCollector",
          "line": 44,
          "signature": "export interface SpanCollector {\n  /** Record a completed span. */\n  recordSpan(span: CompletedSpan): void;\n  /** Retrieve all recorded spans. */\n  spans(): CompletedSpan[];\n  /** Clear all recorded spans. */\n  clear(): void;\n  /** Number of recorded spans. */\n  len(): number;\n  /** Returns true if no spans have been recorded. */\n  isEmpty(): boolean;\n}",
          "documentation": "Interface for collecting completed telemetry spans.\n\nImplementations can store spans in memory, write them to disk, or forward\nthem to an external collector."
        },
        {
          "name": "NoopCollector",
          "line": 67,
          "signature": "export class NoopCollector implements SpanCollector {\n  recordSpan(_span: CompletedSpan): void;\n  spans(): CompletedSpan[];\n  clear(): void;\n  len(): number;\n  isEmpty(): boolean;\n}",
          "documentation": "Discards all spans. Zero-cost default for standalone agents."
        },
        {
          "name": "InMemoryCollector",
          "line": 106,
          "signature": "export class InMemoryCollector implements SpanCollector {\n  recordSpan(span: CompletedSpan): void;\n  spans(): CompletedSpan[];\n  clear(): void;\n  len(): number;\n  isEmpty(): boolean;\n}",
          "documentation": "Stores spans in memory. Useful for testing and debugging."
        },
        {
          "name": "InMemoryTelemetry",
          "line": 157,
          "signature": "export class InMemoryTelemetry implements TelemetryContract {\n  constructor(agentDid?: string);\n  startSpan(name: string, attributes: ReadonlyArray<readonly [string, string]>): SpanId;\n  endSpan(spanId: SpanId): void;\n  emitEvent(event: AuditEvent): void;\n  flush(): void;\n  completedSpans(): CompletedSpan[];\n  events(): AuditEvent[];\n  clear(): void;\n  spanCount(): number;\n  eventCount(): number;\n}",
          "documentation": "In-memory telemetry implementation that stores both spans and events.\n\nWraps InMemoryCollector for span storage and tracks active spans to\nproduce CompletedSpan records when endSpan is called. Also collects\nemitted AuditEvent entries.\n\nImplements TelemetryContract for use in testing and debugging scenarios.\n\nANVIL Spec section 14.1 -- Telemetry Contract."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-telemetry/src/contract.ts",
      "sha256": "26b1c724b21a71f748efe0b4bf83a8bfd3130fd20af29cdf249cb5e9a2716ca2",
      "artifactSha256": "a6d7e8777d899bdaed111061c135f4b0e0899c44d6e6c0f7f094b26c24912783",
      "url": "/reference/source/forge-ts/packages/forge-telemetry/src/contract.ts.txt",
      "declarations": [
        {
          "name": "export const AuditEventKind = {",
          "line": 21,
          "signature": "export const AuditEventKind /* type inferred in source */;",
          "documentation": "Audit event kinds per ANVIL Spec section 14.3.\n\nEach kind corresponds to a category of agent operation that should be\nrecorded in the audit trail."
        },
        {
          "name": "AuditEventKindType",
          "line": 34,
          "signature": "export type AuditEventKindType =\n  (typeof AuditEventKind)[keyof typeof AuditEventKind];",
          "documentation": "An audit event kind value."
        },
        {
          "name": "SpanId",
          "line": 46,
          "signature": "export class SpanId {\n  readonly value: string;\n  static generate(): SpanId;\n  static fromString(id: string): SpanId;\n  toString(): string;\n}",
          "documentation": "A unique span identifier.\n\nEach span started via the TelemetryContract receives a SpanId that must be\npassed to endSpan when the operation completes. IDs are generated as random\nstrings for global uniqueness.\n\nANVIL Spec section 14.1 -- Telemetry Contract (span identification)."
        },
        {
          "name": "AuditEvent",
          "line": 97,
          "signature": "export class AuditEvent {\n  readonly kind: AuditEventKindType;\n  readonly agentDid: string;\n  readonly timestamp: string;\n  readonly details: Record<string, unknown>;\n  readonly signature: string | undefined;\n  static create(\n    kind: AuditEventKindType,\n    agentDid: string,\n    details: Record<string, unknown>\n  ): AuditEvent;\n  withSignature(signature: string): AuditEvent;\n  isSigned(): boolean;\n  toJSON(): Record<string, unknown>;\n}",
          "documentation": "An audit event recording a significant agent operation.\n\nANVIL Spec section 14.3 -- Audit Events."
        },
        {
          "name": "TelemetryContract",
          "line": 175,
          "signature": "export interface TelemetryContract {\n  /**\n   * Start a new span with the given name and attributes.\n   *\n   * @param name - The span name (use dotted notation, e.g., \"anvil.generate\").\n   * @param attributes - Key-value pairs of span attributes.\n   * @returns A unique SpanId for the started span.\n   */\n  startSpan(name: string, attributes: ReadonlyArray<readonly [string, string]>): SpanId;\n\n  /**\n   * End a previously started span.\n   *\n   * @param spanId - The ID returned by startSpan.\n   */\n  endSpan(spanId: SpanId): void;\n\n  /**\n   * Emit an audit event for the agent's audit trail.\n   *\n   * @param event - The audit event to record.\n   */\n  emitEvent(event: AuditEvent): void;\n\n  /**\n   * Flush any buffered telemetry data to the backend.\n   *\n   * @throws {TelemetryError} If the flush operation fails.\n   */\n  flush(): void;\n}",
          "documentation": "ANVIL Spec section 14.1 -- Telemetry Contract.\n\nDefines the telemetry emission interface for ANVIL-compliant agents.\nImplementations collect spans, emit audit events, and support flushing\nbuffered telemetry data to external systems."
        },
        {
          "name": "NoopTelemetry",
          "line": 223,
          "signature": "export class NoopTelemetry implements TelemetryContract {\n  startSpan(_name: string, _attributes: ReadonlyArray<readonly [string, string]>): SpanId;\n  endSpan(_spanId: SpanId): void;\n  emitEvent(_event: AuditEvent): void;\n  flush(): void;\n}",
          "documentation": "No-op telemetry implementation that discards all telemetry data.\n\nUsed as the default for agents that do not need telemetry collection or\nwhen telemetry is disabled. All operations are zero-cost.\n\nANVIL Spec section 14.1 -- Telemetry Contract (default implementation)."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-telemetry/src/error.ts",
      "sha256": "3fd1dcdea6ede75c8218b10a9841e3214f68c22aabf3afa37019516b840dbe0e",
      "artifactSha256": "8223c35012f9eff033ee31a335637ad7be0e63d7dc0b996a1d604d74621f1826",
      "url": "/reference/source/forge-ts/packages/forge-telemetry/src/error.ts.txt",
      "declarations": [
        {
          "name": "export const TelemetryErrorCode = {",
          "line": 17,
          "signature": "export const TelemetryErrorCode /* type inferred in source */;",
          "documentation": "Error types for the forge-telemetry package.\n\nAll errors are typed, actionable, and include enough context to diagnose the\nissue without reading source code.\n\nANVIL Spec section 14 -- Telemetry error conditions.\nError codes for telemetry operations.\n\nEach code maps to a specific category of failure."
        },
        {
          "name": "TelemetryErrorCodeType",
          "line": 35,
          "signature": "export type TelemetryErrorCodeType =\n  (typeof TelemetryErrorCode)[keyof typeof TelemetryErrorCode];",
          "documentation": "A telemetry error code value."
        },
        {
          "name": "TelemetryError",
          "line": 50,
          "signature": "export class TelemetryError extends Error {\n  readonly code: TelemetryErrorCodeType;\n  static spanNotFound(spanId: string): TelemetryError;\n  static spanAlreadyClosed(spanId: string): TelemetryError;\n  static auditEntryInvalid(reason: string): TelemetryError;\n  static auditTrailCorrupted(index: number, reason: string): TelemetryError;\n  static flushFailed(reason: string): TelemetryError;\n  static collectorFull(capacity: number): TelemetryError;\n  static exportFailed(reason: string): TelemetryError;\n}",
          "documentation": "Error type for telemetry operations.\n\nEvery instance includes actionable context: what failed, why, and what the\ndeveloper should check."
        }
      ]
    },
    {
      "path": "forge-ts/packages/forge-telemetry/src/index.ts",
      "sha256": "f6a041fd39ee907ddb2a882d8874d6fd715ca08a46b19838796bed71c55a80b1",
      "artifactSha256": "234cca27018db950dab4560cd88e7dd5eaadfe7f13b07457af26502305807d07",
      "url": "/reference/source/forge-ts/packages/forge-telemetry/src/index.ts.txt",
      "declarations": [
        {
          "name": "export {",
          "line": 21,
          "signature": "export {\n  AuditEventKind,\n  type AuditEventKindType,\n  SpanId,\n  AuditEvent,\n  type TelemetryContract,\n  NoopTelemetry,\n} from './contract.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 31,
          "signature": "export {\n  type CompletedSpan,\n  type SpanCollector,\n  NoopCollector,\n  InMemoryCollector,\n  InMemoryTelemetry,\n} from './collector.js';",
          "documentation": ""
        },
        {
          "name": "export { type AuditEntry, AuditTrail } from './audit.js';",
          "line": 40,
          "signature": "export { type AuditEntry, AuditTrail } from './audit.js';",
          "documentation": ""
        },
        {
          "name": "export {",
          "line": 43,
          "signature": "export {\n  TelemetryErrorCode,\n  type TelemetryErrorCodeType,\n  TelemetryError,\n} from './error.js';",
          "documentation": ""
        }
      ]
    }
  ]
}