CrucibleSignalTrace

Bounded forward-pass trace schema and persistence helpers for Crucible signal captures, layer trajectories, and decode telemetry.

Stack Position

crucible_signal_trace sits above crucible_signal and crucible_tap. It records what happened in a model pass without owning model execution or policy authority.

Installation

def deps do
  [
    {:crucible_signal_trace, "~> 0.1.0"}
  ]
end

Boundary

This package owns trace records, signal records, layer trajectories, JSONL persistence, bounded redaction, and export helpers. It does not run models or decide routes.

Usage

alias CrucibleSignal.SignalRef
alias CrucibleSignalTrace.{ForwardTrace, JSONL}

logits_ref =
  SignalRef.new!(
    trace_id: "trace-1",
    signal_id: "final-logits",
    signal_type: :final_logits
  )

trace =
  ForwardTrace.new!(
    trace_id: "trace-1",
    model_ref: "model:local",
    final_logits: logits_ref,
    cache_summary: %{blocks: 28}
  )

line = JSONL.encode_line!(trace)

Guides

• Quickstart
• Concepts
• Forward Trace
• Provider Neutral Traces
• Layer Trajectory
• JSONL Persistence
• AITrace Export
• Redaction
• Working Examples
• Testing

Examples

• examples/trace_jsonl_mock.exs
• examples/aitrace_export_live.exs

Testing

• Default suite: mix test
• Full local gate: mix ci

Documentation can be generated with mix docs and published to HexDocs.

V5 Status

Status: trace-ingestion-real-artifact-passing.

V5 continues to use "schema_version": "crucible.trace.v4" for the canonical JSONL wire format and expands the accepted event set for backend, model, signal, generation, capability, policy, and route-decision rows.

CrucibleSignalTrace.JSONL.write_event!/2, CrucibleSignalTrace.JSONL.stream!/1, CrucibleSignalTrace.Validate, and CrucibleSignalTrace.Ingest.from_jsonl/2 validate and assemble native Bumblebee and Python/PyTorch traces without inline raw tensor arrays. The V5 gate is recorded at tmp/crucible_v5/transcripts/crucible_signal_trace_mix_ci.log.