README

Opt-in resolution tracing for gosuperscript/axiom. Decorates DelegatingResolver to build a tree-shaped trace that mirrors the recursive resolution call stack, capturing timing, outcomes, and resolver-contributed metadata on each node.

Installation

composer require gosuperscript/axiom-tracing

Requires gosuperscript/axiom ^0.4.0.

Usage

Conditional tracing with callback

use Superscript\Axiom\Context;
use Superscript\Axiom\Resolvers\DelegatingResolver;
use Superscript\Axiom\Tracing\Tracing;
use Superscript\Axiom\Tracing\TracedResult;
use Superscript\Axiom\Tracing\TracingResolver;

$resolver = Tracing::wrap(
    new DelegatingResolver([...]),
    enabled: config('axiom.tracing', false),
);

// Register a callback — fires on every top-level resolution
if ($resolver instanceof TracingResolver) {
    $resolver->onTrace(function (TracedResult $traced) {
        Log::debug('Axiom resolution', ['trace' => $traced->dump()]);
    });
}

// Calling code is unchanged — resolve takes a Source and a Context.
$result = $resolver->resolve($source, new Context());

Tracing an Expression

use Superscript\Axiom\Expression;

$expression = new Expression($source, $resolver);
$result = $expression(['radius' => 5]); // fires the trace callback

Explicit trace retrieval

use Superscript\Axiom\Context;
use Superscript\Axiom\Tracing\TracingResolver;

$tracer = new TracingResolver($delegatingResolver);

$traced = $tracer->traced($source); // optionally pass a Context with bindings/definitions
$traced->result;  // Result<Option<T>>
$traced->trace;   // ResolutionTrace tree
$traced->dump();  // formatted string

Extracting metadata from a trace

// Collect all values for a key across the entire tree
$httpExchanges = $traced->trace->collect('http_response');

// Walk the tree manually
foreach ($traced->trace->children() as $child) {
    $child->getMetadata('http_response');
}

Production use (flat inspector, no tracing)

For extracting resolver metadata without full tracing overhead, pass a flat inspector via the Context:

use Superscript\Axiom\Context;
use Superscript\Axiom\Tracing\ResolutionContext;

$inspector = new ResolutionContext();

$result = $resolver->resolve($source, new Context(inspector: $inspector));
$httpResponse = $inspector->get('http_response');

Components

Example output

TypeDefinition [NumberType] — ok, value: 150, 52ms
└── InfixExpression [*] — ok, value: 150, 51ms
    ├── SymbolSource [base_rate] — ok, value: 100, 3ms
    │   └── StaticSource [static(int)] — ok, value: 100, 0.01ms
    └── InfixExpression [+] — ok, value: 1.5, 45ms
        ├── StaticSource [static(float)] — ok, value: 0.5, 0.01ms
        └── StaticSource [static(int)] — ok, value: 1, 0.01ms

Testing

composer install
vendor/bin/phpunit