Module: lib/core/trace/contracts

Checks declared compiler contracts against what a trace shows the code actually did.

Avenx's contracts (static, pure, deterministic, isolated) are declared in a component and checked by the compiler with pattern matching over source text. That catches the obvious cases and misses everything reached indirectly: a computed that calls a helper that calls Date.now() looks pure to a regular expression.

A trace closes that gap without any new machinery. It already records where every non-deterministic global was read and where every state write happened, and every node knows its causal ancestry — so asking "did anything inside a unit that declared itself deterministic read the clock?" is a walk up the parent chain. The contract stops being a build-time assertion and becomes a claim checked against the run.

The diagnostic codes are the compiler's existing ones, deliberately: a developer who has seen AVX_W33 at build time should recognise it when it arrives from a recording, and avenx explain AVX_W33 should still be the right thing to type.

Source:

Methods

(static) findContractViolations(trace) → {Array:.<{code:: string:, contract:: string:, unit:: string:, detail:: string:, nodeId:: number:}>}

Checks a trace's declared contracts against what it recorded.

Two contracts are checkable from a trace:

  • deterministic — a unit that declared it must not have read Date.now(), new Date() or Math.random(). The trace records exactly where those reads happened.
  • pure — a unit that declared it must not have mutated reactive state. The trace records every write and what caused it.

static and isolated are structural claims the compiler can decide completely from source, so a trace adds nothing to them and they are not re-checked here.

Parameters:
Name Type Description
trace object

The trace to check.
Source:
Returns:

One entry per violation, in recorded order.

Type
Array:.<{code:: string:, contract:: string:, unit:: string:, detail:: string:, nodeId:: number:}>

(static) formatViolation(violation) → {string}

Renders a violation as a single diagnostic line.

Parameters:
Name Type Description
violation object

A violation from findContractViolations.
Source:
Returns:

A line suitable for avenx trace view.

Type
string

(generator, inner) ancestors(node, byId) → {object}

Walks a node's ancestry, nearest first.

Parameters:
Name Type Description
node object

The starting node.
byId Map:.<number:, object:>

Nodes keyed by id.
Source:
Yields:
Each ancestor, nearest first.
Type
object

(inner) label(node) → {string}

Describes a unit for a diagnostic message.

Parameters:
Name Type Description
node object

An action or computed node.
Source:
Returns:

A short label such as CartItem.incQty().

Type
string

(inner) nearestDeclaring(node, byId, contract) → {object|null}

Finds the nearest ancestor that declared a given contract.

Parameters:
Name Type Description
node object

The starting node.
byId Map:.<number:, object:>

Nodes keyed by id.
contract string

The contract name.
Source:
Returns:

The declaring ancestor, if any.

Type
object | null