From 1f8c0496a9997821bfe46f710319df1727ac70c5 Mon Sep 17 00:00:00 2001
From: "homeboy-ci[bot]" <266378653+homeboy-ci[bot]@users.noreply.github.com>
Date: Mon, 18 May 2026 03:40:21 +0000
Subject: [PATCH] feat(engine): add datamachine_engine_snapshot filter at job
 init
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a single filter hook in RunFlowAbility::execute() that fires once
per job, immediately before the engine snapshot is persisted. Filters
receive the assembled snapshot, the job ID, and the source flow + pipeline
rows. Returning a modified array enriches engine_data with context that
lives outside DM core.

Driving use case: Data Machine Code projects active workspace identity
(repo, handle, branch, path) into engine_data so AI directives, abilities,
and tool calls can answer "which repo is this job operating against" —
context DMC already collects but never surfaces into the AI runtime. See
Extra-Chill/data-machine-code#423.

Pattern is intentionally tiny — one apply_filters() call, no new classes,
no schema changes, no CLI surface. The filter is the public extension
point; downstream plugins own the semantics of what they project. DM
core stays agnostic about workspace, repo, or any consumer-specific
concept.

Defensive: filter return value is validated as array; non-array returns
silently preserve the prior snapshot so a misbehaving filter cannot
corrupt engine_data.

Refs Extra-Chill/data-machine-code#423
Refs Extra-Chill/extrachill-docs#31
---
 inc/Abilities/Engine/RunFlowAbility.php | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/inc/Abilities/Engine/RunFlowAbility.php b/inc/Abilities/Engine/RunFlowAbility.php
index 3bcf011a2..75a83badc 100644
--- a/inc/Abilities/Engine/RunFlowAbility.php
+++ b/inc/Abilities/Engine/RunFlowAbility.php
@@ -244,6 +244,30 @@ public function execute( array $input ): array {
 			$engine_snapshot = array_merge( $existing_data, $engine_snapshot );
 		}
 
+		/**
+		 * Filter the engine snapshot before it is persisted for a new job.
+		 *
+		 * Lets extensions enrich the engine_data snapshot with context that
+		 * lives outside DM core. For example, Data Machine Code projects the
+		 * active workspace identity (repo, handle, branch, path) into
+		 * `active_workspace` so directives, abilities, and tool calls can
+		 * read which repo the current job is operating against.
+		 *
+		 * Filters MUST return an array. Returning a non-array silently
+		 * preserves the prior snapshot.
+		 *
+		 * @since 0.10.3
+		 *
+		 * @param array $engine_snapshot The snapshot about to be persisted.
+		 * @param int   $job_id          Job being initialized.
+		 * @param array $flow            Flow row from the database.
+		 * @param array $pipeline        Pipeline row from the database.
+		 */
+		$filtered_snapshot = apply_filters( 'datamachine_engine_snapshot', $engine_snapshot, $job_id, $flow, $pipeline );
+		if ( is_array( $filtered_snapshot ) ) {
+			$engine_snapshot = $filtered_snapshot;
+		}
+
 		datamachine_set_engine_data( $job_id, $engine_snapshot );
 
 		try {