events

quiverlab.trace.events

The unified worked-steps step-event taxonomy (spec §3.8).

This module is the SINGLE import surface for trace events. It RE-EXPORTS the event dataclasses shipped by Plan 03 (groebner) and Plan 04 (Chouhy-Solotar) from their home modules -- it never redefines them -- and DEFINES the one new event, RankStep, which carries a numeric differential matrix over a field plus its rank (the bar/fast engines' notion of a differential; the CS DifferentialEvent carries symbolic bimodule terms instead).

Reconciliation notes (see the plan's taxonomy table): * The requested Differential is Plan 04's DifferentialEvent. * AmbiguityEvent (Plan 04) is folded in. * Dispatch (Plan 03) is reused for BOTH the construction route (monomial vs groebner) AND the engine/resolution choice (bar/fast/bardzell/chouhy-solotar); same dataclass, distinguished by the value of route.

Dispatch dataclass

Dispatch(route: str, reason: str, n_relations: int)

Which lowering route Quiver.algebra took, and why.

ExtDegree dataclass

ExtDegree(degree: int, op: str, space_dim: int, rank_here: int, rank_prev: int, result_dim: int, nrows: int, ncols: int, field: str, matrix: object = None, elided: bool = False, note: str = '')

One degree of an Ext/Tor computation over a minimal resolution: the collapsed Hom (Ext) / tensor (Tor) space dimension at degree n, the connecting map (delta^n for Ext / d_n for Tor) as a matrix, its rank and the neighbouring rank, and the resulting Ext^n / Tor_n dimension. op is "Ext" or "Tor".

ExtReps dataclass

ExtReps(op: str, basis_classes: object = None, chain_basis: object = None, differentials: object = None)

Plan 35 wave 3a: the EXPLICIT (co)cycle representatives of a module Ext / Tor computation -- per degree the basis classes (each a labelled term-sum + a sparse coordinate vector), the ordered Hom / tensor enumeration the vectors index into, and the annihilating differential -- as the single-side {str(degree): ...} payload of quiverlab.modules.complex_reps (captured from the SAME Hom / tensor complex that produced the dims). Emitted ONCE per Ext / Tor run, so the worked-steps module chapter can render the per-degree classes symmetric with the HH-product ProductBasis. op is "ext" / "tor".

The three payload fields default None -- a legacy run without the explicit-reps fields emits no ExtReps (or one whose fields are None), and the renderer falls back to the rank bookkeeping only (tolerance).

ModuleDifferential dataclass

ModuleDifferential(degree: int, kind: str, sym: str, symbol: str, dom_summands: object, cod_summands: object, nrows: int, ncols: int, field: str, cod_is_module: bool = False, dom_is_module: bool = False, mod_name: str = 'M', matrix: object = None, elided: bool = False, note: str = '')

A differential of a module (co)resolution rendered AS A MATRIX over the stated field. dom_summands/cod_summands are the source/target summand vertex lists (with repetition); cod_is_module is True for the augmentation d_0: Q_0 -> M (whose target is the module M itself, not a projective term). sym is "P"/"I", kind "projective"/"injective". matrix is list[list[str]] or None (elided). symbol is the differential's TeX name (e.g. "d_1").

dom_is_module / cod_is_module (Plan 34 adds the domain flag) render that endpoint as the module M itself rather than a direct sum of summands -- used for the self-maps of a module (an arrow action rho_M(a): M -> M or a splitting endomorphism), keeping the map declaration narrow. Both default False (byte-stable); the text/HTML renderers read only the summand lists, so a flagged endpoint falls back to its *_summands rendering there (still honest: M = (+)_v M e_v).

ModuleTerm dataclass

ModuleTerm(degree: int, kind: str, sym: str, summands: object, dim: int, dimvec: object = None)

One term of a module (co)resolution: the direct sum of indecomposable projectives (P_v) or injectives (I_v). summands is the vertex list WITH repetition (e.g. [1, 1, 3] renders as P_1^{2} + P_3); sym is "P" or "I"; kind is "projective" or "injective"; dim is the k-dimension; dimvec maps vertex -> multiplicity (a dict with str/int keys, or None).

ProductBasis dataclass

ProductBasis(kind: str, basis_classes: object = None, chain_basis: object = None, differentials: object = None)

Plan 35 UNIT 2: the EXPLICIT (co)cycle representatives of an HH-product chapter -- per (side, degree) the basis classes (each a labeled term-sum + a sparse coordinate vector), the ordered (co)chain enumeration the vectors index into, and the annihilating differential -- as the JSON-safe {side: {str(degree): ...}} shape of quiverlab.hochschild.products.blocks() (captured at table-build time by quiverlab.hochschild.basis_reps). Emitted ONCE per chapter, before the ProductStep tables; the renderer turns it into per-degree sub-sections (ordered basis -> explicit classes -> differential + a one-line verification sentence) that the structure-constant tables then reference.

All three payload fields default None -- a legacy product object without the explicit-reps fields emits no ProductBasis (or one whose fields are None), and the renderers fall back to the naming-only legend (tolerance).

ProductStep dataclass

ProductStep(kind: str, degrees: object, heading: str = '', lines: object = (), matrix: object = None, note: str = '', dims: object = None, constants: object = None, out_degree: object = None, prime: object = None)

One block of an HH-product worked-steps chapter (cup / cap / bracket / connes_b). kind is the product kind. degrees is the bidegree tuple -- (p, q) for cup/bracket, (p, n) for cap, (n,) for one Connes differential. heading is the TeX map label (e.g. HH^{p} \otimes HH^{q} \to HH^{p+q}), typeset by the renderer. lines is the list of TeX equation lines spelling out the nonzero products in the recorded class bases (cup/cap/bracket); matrix is the induced-B matrix (list[list[str]] of exact coefficient strings) for connes_b, else None. note is an optional one-liner (a vanishing bidegree, the induced rank).

Cayley-table fields (Marco 2026-08-01, cup/cap/bracket only): dims is [dl, dr, dout], constants the raw constants[k][i][j] residue strings, out_degree the target degree, and prime the GF(p) prime (or None) for the balanced-representative display -- the render surface builds the grid from these. All default absent, so a legacy/connes step and the JSON record are unaffected; lines is retained for the JSON prose and as the vanish sentinel.

RankStep dataclass

RankStep(degree: int, side: str, nrows: int, ncols: int, rank: int, field: str, matrix: object = None, elided: bool = False, note: str = '')

One rank computation of a differential matrix over a stated field.

matrix is a list[list[str]] of domain-element string renderings (kept small), or None when elided is True (matrix larger than the elision threshold -- only shape + rank are retained). side is "cochain" (d^n : C^n -> C^{n+1}) or "chain" (b_n : C_n -> C_{n-1}). nrows/ncols are the matrix dimensions (= dim of the target/source cochain space).

ReductionStep dataclass

ReductionStep(word: tuple, rule_lead: tuple, before: dict, after: dict)

One rewrite: the word occurrence reduced, the rule's leading word, and the linear combination (word -> domain element) before and after the step.

ResolutionTerm dataclass

ResolutionTerm(degree: int, n_generators: int, collapsed_dim: int, corners: Any = None)

corners class-attribute instance-attribute

corners: Any = None

The generators' (source, target) vertex pairs, one per generator WITH repetition -- so the report can NAME the term as a direct sum of projective bimodules C_n = (+)_{s in S_n} A e_{o(s)} (x) e_{t(s)} A instead of quoting a bare generator count (Marco 2026-07-29).

None when the engine's term is not vertex-decomposed (the bar resolution over a structure-constants algebra) -- the renderers then omit the line rather than invent a decomposition. Defaulted, so every existing construction and every recorded stream is unchanged.

ResultDims dataclass

ResultDims(kind: str, dims: object, note: str = '')

The AUTHORITATIVE final (co)homology dimensions the engine actually returned (HHTable.dims / .kind), recorded into the trace as the Result source (Plan 34 fix). The three human renderers show THIS as the "Result" line (with the correct HH^ / HH_ variance) rather than re-deriving from the per-degree events, so a trace can never mislabel or misreport what the engine computed; render_text.derive_dims stays a CROSS-CHECK (writer.py raises on drift). note carries an honest one-liner when the engine records no per-degree worked steps (e.g. the fast GF(p) engine), so the report still has a Result line without fabricating steps.

kind is "HH^" (cohomology) or "HH_" (homology); dims is the list of integer dimensions in degree order; note defaults to "".

StepNote dataclass

StepNote(text: str, detail: str = '', heading: bool = False)

A free-form narrative worked-step line (a projective-cover generator choice, the D/Tr steps of an AR translate, ...). text is the headline; detail is an optional indented continuation. Rendered verbatim (escaped per format).

heading (Plan 34) marks a line that OPENS a new worked step: the LaTeX renderer turns it into a numbered \paragraph{Step N. ...} run-in heading (homework style); the text/HTML renderers, which read only text/detail, show it as a plain paragraph (the flag defaults False, so every pre-Plan-34 StepNote renders exactly as before -- byte-stable).