sparkforensics-server 0.5.0 → 0.5.2

package/public/index.html

@@ -23,14 +23,14 @@
           document.documentElement.setAttribute('data-theme', 'light');
       } catch (_) {}
     </script>
-    <script type="module" crossorigin src="./assets/index-DaC8A2FS.js"></script>
+    <script type="module" crossorigin src="./assets/index-B-03mG7K.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-hePW80VL.js">
     <link rel="modulepreload" crossorigin href="./assets/charts-vendor-0VMaLVLN.js">
-    <link rel="modulepreload" crossorigin href="./assets/plan-graph-vendor-B0sEms9Z.js">
-    <link rel="modulepreload" crossorigin href="./assets/react-vendor-BAKt3vny.js">
-    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-Ds0hcZFn.js">
+    <link rel="modulepreload" crossorigin href="./assets/plan-graph-vendor-BYl-AzN5.js">
+    <link rel="modulepreload" crossorigin href="./assets/react-vendor-DEdfrRTJ.js">
+    <link rel="modulepreload" crossorigin href="./assets/DisclosureContext-ZpE6CkHx.js">
     <link rel="stylesheet" crossorigin href="./assets/plan-graph-vendor-DLioOiRN.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-BcqTLKFp.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-2h_TgUAb.css">
   </head>
   <body>
     <div id="root"></div>

package/vendor-core/analyzer.js

@@ -90,7 +90,7 @@ export function findingId(f         )         {
 
 // skew (either branch) and straggler both claim the stage's replayed tail recovery
 // (tailReplayRecoveryMs via tailRecoveryMs): the same slow-task tail reported by two detectors
-// (see "Overlap caveat: skew / straggler" in impact-estimation.md). skew's branch only changes
+// (see "Overlap caveat: skew / straggler" in impact-estimation/caveats-tuning-and-coverage.md). skew's branch only changes
 // the fallback single-task delta on a stage without the replay, so every skew + straggler pair
 // on a stage is flagged. Flags both sides via validationRequired (rather than suppressing
 // either) so neither finding's own diagnostic value is lost; the flag rides the same

package/vendor-core/api-merge-writes.js

@@ -0,0 +1,80 @@
+// DeltaTable API merges run no command node: each internal query is its own root execution, tied
+// together only by a "MERGE operation" description and adjacent ids. One DeltaMerge write is
+// reported per run of such executions, with a path only when no other merge can be mixed into it.
+import { soleLogPath } from './delta-log-paths.js';
+                                               
+                                                      
+
+                                                                                                              
+
+const API_MERGE_COMMAND = 'DeltaMerge';
+
+// Delta labels its MERGE sub-queries "MERGE operation - <phase>", prefixed "Delta: " in some.
+const MERGE_DESCRIPTION = /^(?:Delta: )?MERGE operation\b/;
+
+// The sub-queries that write: "writing new files ...", "Rewriting N files". A group without one
+// only scanned, and a scan may read the merge's source rather than its target.
+const MERGE_WRITE_PHASE = /\b(?:re)?writing\b/i;
+
+                                                                          
+
+// Selected executions have a MERGE description. A SQL MERGE's own sub-queries carry the same
+// description but belong to the MergeIntoCommand execution they share a root with, which is
+// attributed through its own node (resolveDeltaCommandTarget), so they are left out. A sub-query
+// of an API merge may have another of its executions as its root, so a root alone does not exclude.
+function selectMergeExecutions(sql                             )                   {
+  const isSqlMergeRoot = (id                    )          =>
+    id !== undefined && /^Execute\s+MergeIntoCommand\b/.test(sql.get(id)?.planTree?.name ?? '');
+  return [...sql.values()]
+    .filter((exec) => MERGE_DESCRIPTION.test(exec.description ?? '') && !isSqlMergeRoot(exec.rootExecutionId))
+    .sort((a, b) => a.id - b.id);
+}
+
+// A run of consecutive execution ids. Nothing in the log ties the members of one merge together,
+// so adjacency is a guess, and a wrong one fuses or splits merges. Each way it can go wrong is
+// marked `unclean` instead of attributed:
+//   - the ids of two merges that ran concurrently interleave, so their start-time spans overlap;
+//   - a start time is missing, so the span is unknown.
+//   - no member writes, so the one path it names may be a source's.
+// Merges that ran back to back with no other execution between them still fuse into one run; the
+// run then names two paths and gets no target.
+function groupMerges(selected                  )               {
+  const groups               = [];
+  for (const exec of selected) {
+    const last = groups[groups.length - 1];
+    if (last && last.members[last.members.length - 1].id + 1 === exec.id) last.members.push(exec);
+    else groups.push({ members: [exec], unclean: null });
+  }
+  const spans = groups.map(({ members }) => {
+    const starts = members.map((m) => m.startTime);
+    return starts.every((t)              => typeof t === 'number') ? [Math.min(...starts), Math.max(...starts)] : null;
+  });
+  groups.forEach((group, i) => {
+    const mine = spans[i];
+    if (mine === null) { group.unclean = 'start time missing'; return; }
+    const overlaps = spans.some((other, j) => j !== i && other !== null && other[0] <= mine[1] && mine[0] <= other[1]);
+    if (overlaps) group.unclean = 'overlaps another merge in time';
+    else if (!group.members.some((m) => MERGE_WRITE_PHASE.test(m.description ?? ''))) group.unclean = 'no write phase';
+  });
+  return groups;
+}
+
+/** One DeltaMerge write per run of API merge executions; null target unless one path is certain. */
+export function apiMergeWrites(sql                             )                {
+  return groupMerges(selectMergeExecutions(sql)).map((group) => {
+    const first = group.members[0].id;
+    const last = group.members[group.members.length - 1].id;
+    const resolved = group.unclean === null ? soleLogPath(group.members) : null;
+    const span = first === last ? `${first}` : `${first}-${last}`;
+    return {
+      sqlExecutionId: first,
+      nodeId: null,
+      command: API_MERGE_COMMAND,
+      recognized: true,
+      kind: resolved?.kind ?? null,
+      target: resolved?.target ?? null,
+      outputRows: null,
+      raw: `Delta MERGE operation, executions ${span}${group.unclean ? ` (${group.unclean})` : ''}`,
+    };
+  });
+}

package/vendor-core/cli/budgets.js

@@ -3,6 +3,7 @@ import { computeSkewRatio, ENTRY_BY_TYPE,                         } from '../det
 import { effectiveThresholds } from '../threshold-overrides.js';
 import { IMPACT_BAND_ORDER } from '../format-utils.js';
                                                               
+import { PAIR_DELTA_METRICS,                                      } from '../stage-alignment.js';
                                                                  
                                                                 
 
@@ -14,13 +15,23 @@ const IMPACT_BANDS = Object.keys(IMPACT_BAND_ORDER)                ;
                                                                                   
                                                                                                  
                                          
+                                                                                                                        
+                                              
+                                                                                                            
+                                                                                   
+                                          
  
+
+export const STAGE_QUALITIES                                  = ['exact', 'structural', 'aligned'];
+export const DEFAULT_STAGE_BUDGET_QUALITIES                                  = ['exact', 'structural'];
+/** Metrics with a regression direction (higher is worse). Input and output volume are workload, not performance. */
+export const NEUTRAL_PAIR_METRICS                      = new Set(['inputBytes', 'outputBytes']);
                                
                                                                                             
-                                                               
+                                                                                        
                                                 
                  
-                                                                            
+                                                                                                       
                   
  
 
@@ -146,6 +157,50 @@ function checkRegression(comparison                   , maxRegressionPct
     : { name: 'max-regression', metric: regressionMetric, status: 'pass', detail: `Metric "${regressionMetric}" ${pctLabel}, within budget ${maxRegressionPct}%.` };
 }
 
+function checkStageRegression(
+  comparison                   , { metric, maxPct }                  , qualities                                 ,
+)               {
+  const name = 'max-stage-regression'         ;
+  if (!(PAIR_DELTA_METRICS                     ).includes(metric)) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" is not a paired-stage metric (expected one of: ${PAIR_DELTA_METRICS.join(', ')}).` };
+  }
+  if (NEUTRAL_PAIR_METRICS.has(metric)) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" measures workload volume, not performance: it has no regression direction to check.` };
+  }
+  const eligible = comparison.stagePairs.filter((p) => qualities.includes(p.quality));
+  if (eligible.length === 0) {
+    return { name, metric, status: 'inconclusive', detail: comparison.stagePairs.length === 0
+      ? 'No stages were paired between the two runs.'
+      : `None of the ${comparison.stagePairs.length} paired stage(s) has quality ${qualities.join(' or ')}.` };
+  }
+  const measured = eligible
+    .map((pair) => ({ pair, delta: pair.deltas[metric                   ] }))
+    .filter(({ delta }) => delta.baseline != null && delta.delta != null);
+  if (measured.length === 0) {
+    return { name, metric, status: 'inconclusive', detail: `Metric "${metric}" is unavailable for every eligible paired stage.` };
+  }
+  const regressions = measured
+    .filter(({ delta }) => delta.delta  > 0)
+    .map(({ pair, delta }) => ({ pair, delta, pct: delta.baseline === 0 ? Infinity : (delta.delta  / delta.baseline ) * 100 }))
+    .sort((a, b) => b.pct - a.pct || a.pair.pairId.localeCompare(b.pair.pairId));
+  const over = regressions.filter((r) => r.pct > maxPct);
+  const scope = `${measured.length} paired stage(s)`;
+  if (over.length === 0) {
+    const worst = regressions[0];
+    return { name, metric, status: 'pass', detail: worst
+      ? `No paired stage regressed "${metric}" beyond ${maxPct}% across ${scope}; the largest was ${formatPct(worst.pct)} (pair ${worst.pair.pairId}).`
+      : `No paired stage regressed "${metric}" across ${scope}.` };
+  }
+  const listed = over.slice(0, 3).map((r) => `pair ${r.pair.pairId} (${r.pair.quality}) ${formatPct(r.pct)}`).join(', ');
+  const more = over.length > 3 ? `, and ${over.length - 3} more` : '';
+  return { name, metric, status: 'violation',
+    detail: `${over.length} of ${scope} regressed "${metric}" beyond ${maxPct}%: ${listed}${more}.` };
+}
+
+function formatPct(pct        )         {
+  return pct === Infinity ? 'from 0' : `+${pct.toFixed(1)}%`;
+}
+
 function checkFailOnIntroduced(comparison                   , band        )               {
   if (band !== 'all' && !IMPACT_BANDS.includes(band              )) {
     return { name: 'fail-on-introduced', status: 'inconclusive', detail: `Impact band "${band}" is not recognized (expected "all" or one of ${IMPACT_BANDS.join(', ')}).` };
@@ -198,6 +253,11 @@ export function evaluateBudgets({ appModel, catalog, budgets, comparison, thresh
   for (const { metric, maxPct } of budgets.regressionBudgets ?? []) {
     pushComparisonBudget(results, comparison, 'max-regression', (c) => checkRegression(c, maxPct, metric), metric);
   }
+  const stageQualities = budgets.stageQualities ?? DEFAULT_STAGE_BUDGET_QUALITIES;
+  for (const budget of budgets.stageRegressionBudgets ?? []) {
+    pushComparisonBudget(results, comparison, 'max-stage-regression',
+      (c) => checkStageRegression(c, budget, stageQualities), budget.metric);
+  }
   if (budgets.failOnIntroduced !== undefined) {
     pushComparisonBudget(results, comparison, 'fail-on-introduced',
       (c) => checkFailOnIntroduced(c, budgets.failOnIntroduced ));

package/vendor-core/cli/regression-budgets.js

@@ -4,6 +4,9 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { COMPARISON_METRIC_KEYS } from '../run-comparison.js';
+import { PAIR_DELTA_METRICS } from '../stage-alignment.js';
+import { NEUTRAL_PAIR_METRICS, STAGE_QUALITIES } from './budgets.js';
+                                                       
 
                                                                      
                                                                                      
@@ -81,3 +84,35 @@ export function combineRegressionBudgets(sources                          )
   }
   return sources.map((s) => s.budget);
 }
+
+/** Refuses a stage budget metric that is not a paired-stage metric or has no regression direction. */
+export function assertStageBudgetMetric(metric        , origin        )       {
+  if (!(PAIR_DELTA_METRICS                     ).includes(metric)) {
+    throw new Error(`${origin}: unknown paired-stage metric "${metric}" (expected one of: ${PAIR_DELTA_METRICS.filter((m) => !NEUTRAL_PAIR_METRICS.has(m)).join(', ')}).`);
+  }
+  if (NEUTRAL_PAIR_METRICS.has(metric)) {
+    throw new Error(`${origin}: "${metric}" measures workload volume, not performance, so it has no regression direction to budget.`);
+  }
+}
+
+/** One `--stage-regression-budget` value, `<metric>:<pct>`, over the paired-stage metrics. */
+export function parseStageRegressionBudgetFlag(spec        )                   {
+  const origin = `--stage-regression-budget "${spec}"`;
+  const colon = spec.indexOf(':');
+  if (colon === -1) throw new Error(`${origin}: expected <metric>:<pct>.`);
+  const metric = spec.slice(0, colon);
+  const pct = spec.slice(colon + 1);
+  assertStageBudgetMetric(metric, origin);
+  if (!PCT_PATTERN.test(pct)) throw new Error(`${origin}: "${pct}" is not a non-negative percentage.`);
+  return { metric, maxPct: Number(pct) };
+}
+
+/** The pair qualities a stage budget reads, from a comma list such as `exact,structural`. */
+export function parseStageQualities(list        , origin        )                         {
+  const qualities = list.split(',').map((q) => q.trim()).filter(Boolean);
+  const bad = qualities.find((q) => !(STAGE_QUALITIES                     ).includes(q));
+  if (qualities.length === 0 || bad !== undefined) {
+    throw new Error(`${origin}: ${bad === undefined ? 'no quality given' : `unknown quality "${bad}"`} (expected a list from: ${STAGE_QUALITIES.join(', ')}).`);
+  }
+  return qualities                          ;
+}

package/vendor-core/comparison-output.js

@@ -0,0 +1,50 @@
+import { buildComparison,                                             } from './run-comparison.js';
+import { comparisonVerdict,                            } from './comparison-verdict.js';
+import { redactComparison } from './redact.js';
+                                                    
+
+                                                                                             
+
+// The comparison a surface reports: the CLI's `comparison` object and the shared part of MCP
+// compare_runs. A field added here reaches every surface.
+// `stagePairs` is the one large field (a row per paired stage), so the `summary` view leaves it out.
+                                                                 
+                           
+                                                                                            
+                                                                                                           
+                                                   
+
+/** `full` carries every field (the CLI); `summary` leaves out `stagePairs` (MCP, which returns them
+ * only when asked). */
+                                                
+
+/** The reported projection of a comparison. Key order is the CLI's JSON order. */
+export function comparisonOutput(comparison                   , view                 = 'full')                   {
+  return {
+    verdict: comparisonVerdict(comparison),
+    confidence: comparison.confidence,
+    reason: comparison.reason,
+    matchedCoverage: comparison.matchedCoverage,
+    runtimeCoverage: comparison.runtimeCoverage,
+    metrics: comparison.metrics,
+    findings: comparison.findings,
+    comparisonSchemaVersion: comparison.comparisonSchemaVersion,
+    ...(view === 'full' ? { stagePairs: comparison.stagePairs } : {}),
+    unmatched: comparison.unmatched,
+    replanned: comparison.replanned,
+    bookkeepingStageIds: comparison.bookkeepingStageIds,
+    executionAlignment: comparison.executionAlignment,
+  };
+}
+
+/** Diffs the two runs and applies `redact` here, so no surface can skip it (stage names carry raw
+ * Spark text that can embed a host or IP). `comparison` is the (redacted) raw result for budgets
+ * and Markdown; `output` is the projection to serialize. */
+export function buildComparisonOutput(
+  baseline                    , candidate                    ,
+  { redact, normalizePath, view }                                                               = {},
+)                                                              {
+  const built = buildComparison(baseline, candidate, { normalizePath });
+  const comparison = redact ? redactComparison(built) : built;
+  return { comparison, output: comparisonOutput(comparison, view) };
+}

package/vendor-core/core-source-hash.txt

@@ -1 +1 @@
-ab36c5fdcdc1a32a4e6206459e843e8d2267a90e6f1de29671827315d81bc374
+7aaca3af812e0e5a4f4632ad7577fc438b589520a27422ce8c986b156de82260

package/vendor-core/delta-commands.js

@@ -0,0 +1,13 @@
+// Delta write commands whose root node is a bare name in sparkPlanInfo on real logs. The parser keeps
+// their `Arguments:` line (event-handlers.ts) and delta-targets.ts reads their target from it; the
+// handler table there is typed by this list, so a command added here must get a handler.
+export const DELTA_COMMANDS = [
+  'MergeIntoCommand', 'UpdateCommand', 'DeleteCommand', 'WriteIntoDelta', 'WriteIntoDeltaCommand',
+  'SaveIntoDataSourceCommand',
+]         ;
+
+                                                           
+
+export function isDeltaCommand(name        )                       {
+  return (DELTA_COMMANDS                     ).includes(name);
+}

package/vendor-core/delta-log-paths.js

@@ -0,0 +1,42 @@
+// The `<table path>/_delta_log` paths that plans name: the only trace of which Delta table a command
+// or API merge touched when its plan carries no target. A scan may read a source too, so callers
+// take a path only when exactly one is named.
+import { walkPlanTree } from './plan-tree-walk.js';
+import { isCut,                  } from './write-target-args.js';
+                                               
+
+// A URI or absolute path before `/_delta_log`, as printed in `... State #0 - <path>/_delta_log[cols]`
+// scans and `DeltaLogFileIndex [<path>/_delta_log/<file>, ...]`.
+const DELTA_LOG_PATH = /((?:[A-Za-z][A-Za-z0-9+.-]*:\/{1,3}|\/)[^\s,[\]()#]+?)\/_delta_log(?=[/[\],\s)]|$)/g;
+
+                                                              
+
+// Every distinct table path named in the plans; `unreliable` when a plan is missing or a path cut.
+function deltaLogPaths(executions                                  )           {
+  const paths = new Set        ();
+  let unreliable = false;
+  for (const exec of executions) {
+    if (!exec.planTree) { unreliable = true; continue; }
+    walkPlanTree(exec.planTree, (node) => {
+      for (const text of [node.name, node.detail ?? '']) {
+        const mentions = text.split('/_delta_log').length - 1;
+        if (mentions === 0) continue;
+        const matches = [...text.matchAll(DELTA_LOG_PATH)];
+        // A `/_delta_log` that is not read as a path is a table this set cannot name.
+        if (matches.length < mentions) unreliable = true;
+        for (const m of matches) {
+          if (isCut(m[1])) unreliable = true;
+          else paths.add(m[1].replace(/\/+$/, ''));
+        }
+      }
+    }, { dedupe: true });
+  }
+  return { paths, unreliable };
+}
+
+/** The one table path the plans of `executions` name, or null for none, several or an unreadable plan. */
+export function soleLogPath(executions                                  )                     {
+  const { paths, unreliable } = deltaLogPaths(executions);
+  const [path] = paths;
+  return !unreliable && paths.size === 1 ? { kind: 'path', target: path } : null;
+}

package/vendor-core/delta-targets.js

@@ -0,0 +1,127 @@
+// Delta write targets that the plan node's simpleString does not carry. A Delta command node is a
+// bare name in sparkPlanInfo on real logs; its target is read from the `Arguments:` line the parser
+// keeps (SqlExecution.commandArguments, one reader per command in COMMANDS), and for a command that
+// always scans its target (MERGE, UPDATE, DELETE) from the single `_delta_log` path of the executions
+// sharing its root. A write command may read another Delta table as its source, so it never takes
+// that step. Otherwise the target is null: a rule that cannot name exactly one target names none.
+import { isDeltaCommand,                   } from './delta-commands.js';
+import { soleLogPath } from './delta-log-paths.js';
+import { isCut, splitArgs, tableName,                  } from './write-target-args.js';
+                                                         
+                                                      
+
+                                                                                                       
+
+                                                                       
+
+/** Executions grouped by rootExecutionId, each group excluding the root itself. */
+export function indexByRoot(sql                               )                   {
+  const byRoot = new Map                            ();
+  for (const exec of sql.values()) {
+    if (exec.rootExecutionId === undefined || exec.rootExecutionId === exec.id) continue;
+    const list = byRoot.get(exec.rootExecutionId);
+    if (list) list.push(exec);
+    else byRoot.set(exec.rootExecutionId, [exec]);
+  }
+  return byRoot;
+}
+
+// The text after `<Command>\nArguments: `, or null when the execution kept none for this command.
+function argumentsOf(exec                  , command        )                {
+  const kept = exec.commandArguments;
+  const head = `${command}\nArguments: `;
+  return kept !== undefined && kept.startsWith(head) ? kept.slice(head.length) : null;
+}
+
+// A catalog table is printed as its quoted identifier, `catalog`.`db`.`t`, as one top-level
+// argument. Two or more such arguments (or none) leave the table unnamed. The session catalog is
+// implied by a Hive or V1 table name, so it is dropped: `spark_catalog`.`db`.`t` is db.t.
+const QUOTED_TABLE = /^`[^`]+`(?:\.`[^`]+`){1,2}$/;
+
+function tableFromArguments(args        )                     {
+  const candidates = splitArgs(args).filter((arg) => QUOTED_TABLE.test(arg.text));
+  if (candidates.length !== 1 || !candidates[0].terminated) return null;
+  const name = tableName(candidates[0].text);
+  if (!name || isCut(name)) return null;
+  const parts = name.split('.');
+  return { kind: 'table', target: parts.length === 3 && parts[0] === 'spark_catalog' ? parts.slice(1).join('.') : name };
+}
+
+// SaveIntoDataSourceCommand prints `<provider>@<hash>, [k=v, k2=v2], <mode>`. The target is the
+// one `path` option of a Delta provider.
+function pathFromSaveOptions(args        )                     {
+  const options = splitArgs(args)[1];
+  if (!options?.terminated || !/^\[[\s\S]*\]$/.test(options.text)) return null;
+  const body = options.text.slice(1, -1);
+  const keys = [...body.matchAll(/(?:^|, )([A-Za-z0-9_.-]+)=/g)];
+  const paths = keys.flatMap((key, i) => {
+    if (key[1].toLowerCase() !== 'path') return [];
+    return [body.slice(key.index  + key[0].length, i + 1 < keys.length ? keys[i + 1].index  : body.length)];
+  });
+  if (paths.length !== 1 || isCut(paths[0]) || /\*{5,}\(redacted\)/.test(paths[0])) return null;
+  return { kind: 'path', target: paths[0] };
+}
+
+                          
+                                                                       
+                                                  
+                                                                                                
+                       
+ 
+
+const tableCommand                 = { fromArguments: tableFromArguments, scansTarget: false };
+const scanningTableCommand                 = { ...tableCommand, scansTarget: true };
+
+// One entry per Delta command: a new command is added here (and to DELTA_COMMANDS), not in the resolver.
+const COMMANDS                                       = {
+  MergeIntoCommand: scanningTableCommand,
+  UpdateCommand: scanningTableCommand,
+  DeleteCommand: scanningTableCommand,
+  WriteIntoDelta: tableCommand,
+  WriteIntoDeltaCommand: tableCommand,
+  // Only the arguments say a save is a Delta one; a JDBC save with a Delta table in its source
+  // would otherwise take that table as its target.
+  SaveIntoDataSourceCommand: {
+    fromArguments: (args) => (args.includes('DeltaDataSource') ? pathFromSaveOptions(args) : null),
+    scansTarget: false,
+  },
+};
+
+/** Target of a Delta command whose simpleString names none; `node` must be the root of `exec`'s plan. */
+export function resolveDeltaCommandTarget(
+  command        , exec                  , node          , byRoot                  ,
+)                     {
+  if (!isDeltaCommand(command) || node !== exec.planTree) return null;
+  const handler = COMMANDS[command];
+  const args = argumentsOf(exec, command);
+  const found = args === null ? null : handler.fromArguments(args);
+  if (found || !handler.scansTarget) return found;
+  // Child executions are the root's own only when it is the root: a command run under another
+  // execution shares that execution's children, which may belong to unrelated work.
+  return exec.rootExecutionId === exec.id ? soleLogPath(byRoot.get(exec.id) ?? []) : null;
+}
+
+// An append or overwrite of an existing Delta table (saveAsTable, INSERT INTO or OVERWRITE) is an
+// `AppendDataExecV1` or `OverwriteByExpressionExecV1` whose first argument is the table object:
+// `DeltaTableV2(<session>,<path>,Some(CatalogTable(\nCatalog: c\nDatabase: d\nTable: t\n...)),...)`.
+// Its CatalogTable block names the table; a path-based table has `None` there and only the path.
+const DELTA_TABLE_V2 = /^\w+ DeltaTableV2\([^,\s]*,([^,\n]*),(?:Some\(CatalogTable\(\n(?:Catalog: (\S+)\n)?Database: (\S+)\nTable: (\S+)\n|None,)/;
+const SIMPLE_NAME = /^[A-Za-z0-9_$]+$/;
+
+/** Target of a V1-fallback write on a DeltaTableV2 table, or null when the detail has another shape. */
+export function parseDeltaTableV2(detail        )                     {
+  const m = DELTA_TABLE_V2.exec(detail);
+  if (!m) return null;
+  const [, path, catalog, database, table] = m;
+  if (table === undefined) return path && !isCut(path) ? { kind: 'path', target: path } : null;
+  if (![database, table, catalog ?? 'spark_catalog'].every((part) => SIMPLE_NAME.test(part))) return null;
+  // The session catalog is implied by a V1 name, so it is dropped (as for a Delta command).
+  const name = `${database}.${table}`;
+  return { kind: 'table', target: catalog === undefined || catalog === 'spark_catalog' ? name : `${catalog}.${name}` };
+}
+
+/** The append a Delta CTAS or RTAS runs under its own root: its staged table has no name. */
+export function isStagedDeltaWrite(write                                      )          {
+  return (write.command === 'AppendDataExecV1' || write.command === 'OverwriteByExpressionExecV1')
+    && /^\w+ \S*DeltaCatalog\$StagedDeltaTableV2@/.test(write.raw);
+}