- New sequence_utils.constrained_walk(): backward feasibility (unsatisfiable raises before any draw) + forward sampling through the engine's real history-dependent weights; stall fallback to bare weights; unconstrained walks are draw-identical to the plain engine

- Progression.generate(style=, bars=, beats=, pins=, end=, avoid=) with full engine parameter pass-through; the progression() factory style path delegates to it
- Keyless generation emits a KEY-RELATIVE value (scale-proof major-relative romans, new RomanChord.major_relative) - prints romans unbound, resolves at bind; key= still yields concrete chords
- freeze(end=, pins=, avoid=): hybrid constraints on the live engine; bar 1 stays the journey's current chord; unconstrained freeze routes through the kernel with unchanged seeded output
- WeightedGraph.nodes(); style→scale inference for int constraints (end=1)

Author: Simon Holliday

api-cheatsheet.md

@@ -21,7 +21,7 @@ The top-level controller for a musical piece.
 | `form_jump(section_name) -> None` | Jump the form to a named section immediately. |
 | `form_next(section_name) -> None` | Queue the next section — takes effect when the current section ends. |
 | `form_state *(property)*` | The active ``subsequence.form_state.FormState``, or ``None`` if ``form()`` has not been called. |
-| `freeze(bars) -> 'Progression'` | Capture a chord progression from the live harmony engine. |
+| `freeze(bars, end, pins, avoid) -> 'Progression'` | Capture a chord progression from the live harmony engine. |
 | `get_tweaks(name) -> Dict[str, Any]` | Return a copy of the current tweaks for a running pattern. |
 | `harmonic_state *(property)*` | The active ``HarmonicState``, or ``None`` if ``harmony()`` has not been called. |
 | `harmony(style, cycle_beats, dominant_7th, gravity, nir_strength, minor_turnaround_weight, root_diversity, reschedule_lookahead, progression) -> None` | Configure the harmonic logic and chord change intervals. |
@@ -219,6 +219,7 @@ A frozen sequence of :class:`ChordSpan` — the governing harmony value.
 | `describe(key, scale) -> str` | A readable, one-chord-per-line summary. |
 | `events() -> Tuple[subsequence.progressions.ChordEvent, ...]` | The realised timeline as a tuple (iteration, materialised). |
 | `extend(*extensions, only) -> 'Progression'` | Add chord extensions (``7``/``9``/``11``/``13``/``"sus4"``/...) to every span. |
+| `generate(style, bars, beats, key, scale, seed, rng, pins, end, avoid, dominant_7th, gravity, nir_strength, minor_turnaround_weight, root_diversity) -> 'Progression'` | Generate a progression from a chord-graph walk — the hybrid generator. |
 | `inversions(spec) -> 'Progression'` | Set chord inversions — a single int for all spans, or a list cycled per span. |
 | `is_concrete *(property)*` | True when every span is key-independent (no romans/degrees). |
 | `length *(property)*` | Total length in beats (the sum of span lengths). |
@@ -335,7 +336,7 @@ A sequence of Motifs with segmentation preserved.
 | `between(low, high, step) -> subsequence.harmonic_rhythm.HarmonicRhythm` | A harmonic rhythm that varies *between* two lengths (in beats). |
 | `parse_chord(name) -> subsequence.chords.Chord` | Parse a chord name like ``"Cm7"`` or ``"Dbmaj7"`` into a :class:`Chord`. |
 | `register_chord_quality(name, intervals, suffix) -> None` | Register a custom chord quality for use everywhere chords are used. |
-| `progression(source, beats, style, bars, key, seed, rng, dominant_7th, gravity, nir_strength) -> subsequence.progressions.Progression` | Build a :class:`Progression` — the lowercase factory. |
+| `progression(source, beats, style, bars, key, scale, seed, rng, pins, end, avoid, dominant_7th, gravity, nir_strength, minor_turnaround_weight, root_diversity) -> subsequence.progressions.Progression` | Build a :class:`Progression` — the lowercase factory. |
 | `motif(degrees, beats, velocities, durations, probabilities, length) -> subsequence.motifs.Motif` | The lowercase shortcut: a melody as 1-based scale degrees. |
 | `vl_distance(source, target, pitch_classes) -> int` | Voice-leading distance between two chords (Tymoczko's taxicab metric). |
 | `branch_sequence(pitches, depth, path, mutation, rng) -> List[int]` | Navigate a fractal tree of pitch-sequence transforms and return one variation. |
@@ -351,6 +352,7 @@ Functions for generating and transforming sequences.
 |---|---|
 | `branch_sequence(pitches, depth, path, mutation, rng) -> List[int]` | Navigate a fractal tree of pitch-sequence transforms and return one variation. |
 | `build_metric_weights(time_signature, grid) -> List[float]` | Per-step metric weights for one bar — how "strong" each grid position is. |
+| `constrained_walk(graph, start, length, rng, pins, end, avoid, weight_modifier, before_choice, after_choice) -> List[~T]` | Walk a weighted graph under constraints — the shared hybrid kernel. |
 | `de_bruijn(k, n) -> List[int]` | Generate a de Bruijn sequence B(k, n). |
 | `fibonacci_rhythm(steps, length) -> List[float]` | Generate beat positions spaced by the golden ratio (Fibonacci spiral). |
 | `generate_bresenham_sequence(steps, pulses) -> List[int]` | Generate a rhythm using Bresenham's line algorithm. |

subsequence/composition.py

@@ -28,6 +28,7 @@
 import subsequence.pattern
 import subsequence.pattern_builder
 import subsequence.progressions
+import subsequence.sequence_utils
 import subsequence.sequencer
 import subsequence.voicings
 import subsequence.web_ui
@@ -1561,7 +1562,13 @@ def harmony (
 		# A re-call invalidates whatever the horizon had planned.
 		self._harmony_horizon.invalidate_future()
 
-	def freeze (self, bars: int) -> "Progression":
+	def freeze (
+		self,
+		bars: int,
+		end: typing.Optional[typing.Any] = None,
+		pins: typing.Optional[typing.Dict[int, typing.Any]] = None,
+		avoid: typing.Optional[typing.Sequence[typing.Any]] = None,
+	) -> "Progression":
 
 		"""Capture a chord progression from the live harmony engine.
 
@@ -1573,21 +1580,36 @@ def freeze (self, bars: int) -> "Progression":
 		continuing compositional journey so section progressions feel like parts
 		of a whole rather than isolated islands.
 
+		The hybrid constraints compile into the walk: ``end=`` fixes the last
+		bar ("end on V at bar 8"), ``pins=`` fix any 1-based bar, ``avoid=``
+		excludes chords throughout.  Specs follow the progression-element
+		grammar (ints where diatonic, roman/name strings where chromatic) and
+		resolve against the composition key and scale.  A backward
+		feasibility pass guarantees satisfiability before any chord is drawn;
+		the forward walk keeps the engine's real history-dependent weighting.
+		Bar 1 is always the engine's current chord — the journey continues —
+		so ``pins={1: ...}`` may only name it redundantly.
+
 		Parameters:
 			bars: Number of chords to capture (one per harmony cycle).
+			end: The chord at the final bar — ``end="V"`` is the cadential
+				major dominant in minor.
+			pins: ``{bar: chord}`` — 1-based fiat positions.
+			avoid: Chords excluded from the walk.
 
 		Returns:
 			A :class:`Progression` with the captured chords and trailing
 			history for NIR continuity.
 
 		Raises:
-			ValueError: If :meth:`harmony` has not been called first.
+			ValueError: If :meth:`harmony` has not been called first, or the
+				constraints are contradictory or unsatisfiable.
 
 		Example::
 
 			composition.harmony(style="functional_major", cycle_beats=4)
-			verse  = composition.freeze(8)   # 8 chords, engine advances
-			chorus = composition.freeze(4)   # next 4 chords, continuing on
+			verse  = composition.freeze(8, end="V")   # the verse sets up the chorus
+			chorus = composition.freeze(4)            # next 4 chords, continuing on
 			composition.section_chords("verse",  verse)
 			composition.section_chords("chorus", chorus)
 		"""
@@ -1597,6 +1619,23 @@ def freeze (self, bars: int) -> "Progression":
 		if bars < 1:
 			raise ValueError("bars must be at least 1")
 
+		scale = self.scale or "ionian"
+		key_pc = subsequence.chords.key_name_to_pc(self.key) if self.key is not None else hs.key_root_pc
+
+		resolved_pins = {
+			position: subsequence.progressions.resolve_constraint(spec, key_pc, scale, f"pins[{position}]")
+			for position, spec in (pins or {}).items()
+		}
+		resolved_end = subsequence.progressions.resolve_constraint(end, key_pc, scale, "end") if end is not None else None
+		resolved_avoid = [subsequence.progressions.resolve_constraint(spec, key_pc, scale, "avoid") for spec in (avoid or [])]
+
+		if 1 in resolved_pins and resolved_pins[1] != hs.current_chord:
+			raise ValueError(
+				f"pins[1]={resolved_pins[1].name()} conflicts with the engine's current chord "
+				f"({hs.current_chord.name()}) — bar 1 of a freeze continues the journey; "
+				"pin a later bar, or use pin_chord() for playback fiat"
+			)
+
 		# Per-call salted stream (freeze:1, freeze:2, ...): each call's draws
 		# are independent of every other consumer, so frozen progressions are
 		# reproducible WITHOUT play() and adding a call cannot shift a
@@ -1611,11 +1650,23 @@ def freeze (self, bars: int) -> "Progression":
 			hs.rng = stream
 
 		try:
-			collected: typing.List[subsequence.chords.Chord] = [hs.current_chord]
-
-			for _ in range(bars - 1):
-				hs.step()
-				collected.append(hs.current_chord)
+			# The kernel with the engine's own hooks is draw-for-draw the old
+			# step() loop when unconstrained — one walk path for both.
+			def _commit (chosen: subsequence.chords.Chord) -> None:
+				hs.current_chord = chosen
+
+			collected = subsequence.sequence_utils.constrained_walk(
+				hs.graph,
+				hs.current_chord,
+				bars,
+				rng = hs.rng,
+				pins = resolved_pins,
+				end = resolved_end,
+				avoid = resolved_avoid,
+				weight_modifier = hs._transition_weight,
+				before_choice = hs._record_transition_source,
+				after_choice = _commit,
+			)
 
 			# Advance past the last captured chord so the next freeze() call or
 			# live playback does not duplicate it.

subsequence/harmonic_state.py

@@ -264,14 +264,25 @@ def _transition_weight (
 
 		return (1.0 + boost) * nir_score * diversity
 
+	def _record_transition_source (self, chord: subsequence.chords.Chord) -> None:
+
+		"""History bookkeeping for one transition: the outgoing chord enters history.
+
+		The first half of :meth:`step` — exposed so a constrained walk can
+		interleave it with its own draws (``before_choice``) and the NIR
+		weighting sees exactly the context it would live.
+		"""
+
+		self.history.append(chord)
+		if len(self.history) > 4:
+			self.history.pop(0)
+
 	def step (self) -> subsequence.chords.Chord:
 
 		"""Advance to the next chord based on the transition graph."""
 
 		# Update history before choosing next (so structure tracks the path)
-		self.history.append(self.current_chord)
-		if len(self.history) > 4:
-			self.history.pop(0)
+		self._record_transition_source(self.current_chord)
 
 		# Decision path: chord changes occur here; key changes are not automatic.
 		self.current_chord = self.graph.choose_next(self.current_chord, self.rng, weight_modifier=self._transition_weight)
@@ -291,9 +302,7 @@ def plan_next (self) -> subsequence.chords.Chord:
 
 		saved_history = list(self.history)
 
-		self.history.append(self.current_chord)
-		if len(self.history) > 4:
-			self.history.pop(0)
+		self._record_transition_source(self.current_chord)
 
 		try:
 			return self.graph.choose_next(self.current_chord, self.rng, weight_modifier=self._transition_weight)
@@ -310,9 +319,7 @@ def commit_chord (self, chord: subsequence.chords.Chord) -> subsequence.chords.C
 		``step()`` records it).
 		"""
 
-		self.history.append(self.current_chord)
-		if len(self.history) > 4:
-			self.history.pop(0)
+		self._record_transition_source(self.current_chord)
 
 		self.current_chord = chord