feat(tasks): find the newest sequence for a template, across every anchor (#3360)

The mapper could answer "what happened to THIS object" three ways and "has this
approval ever run" not at all. Every existing finder constrains
anchor_object_uuid, so an aggregate over a template had no anchor to pass.

buildiq is the caller that needed it. Its automation dry-run panel used to read
the newest ApprovalStep on a chain; when #3302 retired that surface there was no
replacement for the aggregate, so the panel degraded to reporting nothing at all
(buildiq#651). This restores it.

One row off the existing template_id index, ordered like its siblings and
limited in the QUERY rather than trimmed in PHP.

Tested with a negative control, not just a green run: adding an anchor predicate
and dropping the limit makes the new test fail with "Failed asserting that an
array does not contain 'anchor_object_uuid'". A finder that quietly constrained
the anchor would answer a different question than the caller asked, which is the
one thing this method must not do.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rubenvdlinde

lib/Db/TaskSequenceMapper.php

@@ -98,6 +98,43 @@ public function findRunning(string $anchorObjectUuid, string $templateId): ?Task
 		return ($rows[0] ?? null);
 	}//end findRunning()
 
+	/**
+	 * The newest sequence opened from a template, across EVERY anchor.
+	 *
+	 * The other finders here answer "what happened to THIS object". This one
+	 * answers "has this approval ever run", which is what a designer surface
+	 * needs to report a template's last outcome without knowing an object to
+	 * ask about.
+	 *
+	 * buildiq's automation dry-run panel is the caller: it used to read the
+	 * newest ApprovalStep on the chain, and when #3302 retired that surface the
+	 * per-anchor finders could not replace it — an aggregate over the template
+	 * has no anchor to pass. Without this the panel degraded to reporting
+	 * nothing at all (buildiq#651).
+	 *
+	 * Indexed by `template_id` and ordered like its siblings, so it is one row
+	 * off the same index rather than a scan.
+	 *
+	 * @param string $templateId The compiled template id.
+	 *
+	 * @return TaskSequence|null The newest sequence for the template, or null when none has run.
+	 *
+	 * @spec openspec/changes/flow-approval-consolidation/specs/flow-approval-consolidation/spec.md#requirement-an-approval-is-an-ordered-task-sequence-with-o
+	 */
+	public function findNewestForTemplate(string $templateId): ?TaskSequence {
+		$qb = $this->db->getQueryBuilder();
+		$qb->select('*')
+			->from($this->getTableName())
+			->where($qb->expr()->eq('template_id', $qb->createNamedParameter($templateId)))
+			->orderBy('opened_at', 'DESC')
+			->addOrderBy('id', 'DESC')
+			->setMaxResults(1);
+
+		$rows = $this->findEntities(query: $qb);
+
+		return ($rows[0] ?? null);
+	}//end findNewestForTemplate()
+
 	/**
 	 * Every sequence for an anchor and template, newest first.
 	 *

tests/Unit/Db/TaskSequenceMapperQueriesTest.php

@@ -76,6 +76,32 @@ public function testFindNewestForAnchorOrdersByOpenTimeDescending(): void {
 		self::assertNotSame([], $orderings, 'history must be explicitly ordered, never id-lucky');
 	}//end testFindNewestForAnchorOrdersByOpenTimeDescending()
 
+	public function testFindNewestForTemplateDoesNotFilterOnAnAnchor(): void {
+		$mapper = new TaskSequenceMapper(db: $this->connectionWith(rows: [$this->row('seq-9', 'rejected')]));
+
+		$newest = $mapper->findNewestForTemplate(templateId: 'tpl-1');
+
+		self::assertSame('seq-9', $newest->getUuid());
+
+		// The whole point of this finder: it aggregates ACROSS anchors, so an
+		// anchor predicate would silently answer a different question than the
+		// caller asked. Its siblings all constrain the anchor; this one must not.
+		$predicates = array_filter($this->calls, static fn (array $call): bool => $call[0] === 'expr.eq');
+		$columns = array_map(static fn (array $call): mixed => $call[1], $predicates);
+		self::assertContains('template_id', $columns);
+		self::assertNotContains('anchor_object_uuid', $columns, 'a template-wide finder must not constrain the anchor');
+
+		// One row off the index, not a scan the caller trims.
+		$limits = array_filter($this->calls, static fn (array $call): bool => $call[0] === 'setMaxResults');
+		self::assertNotSame([], $limits, 'the newest row must be taken by the query, not in PHP');
+	}//end testFindNewestForTemplateDoesNotFilterOnAnAnchor()
+
+	public function testFindNewestForTemplateWithNoRunIsNull(): void {
+		$mapper = new TaskSequenceMapper(db: $this->connectionWith(rows: []));
+
+		self::assertNull($mapper->findNewestForTemplate(templateId: 'tpl-1'));
+	}//end testFindNewestForTemplateWithNoRunIsNull()
+
 	public function testATerminalStatusReadsAsTerminal(): void {
 		$sequence = new TaskSequence();
 		$sequence->setStatus(TaskSequence::STATUS_REJECTED);