@prisma-next/cli 0.12.0-dev.3 → 0.12.0-dev.30

package/src/commands/telemetry/index.ts

@@ -0,0 +1,107 @@
+import { userConfigPath, writeUserConfig } from '@prisma-next/cli-telemetry';
+import { Command } from 'commander';
+import {
+  addGlobalOptions,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../../utils/command-helpers';
+import { formatCommandHelp } from '../../utils/formatters/help';
+import {
+  type CommonCommandOptions,
+  parseGlobalFlags,
+  parseGlobalFlagsOrExit,
+} from '../../utils/global-flags';
+import { isCI } from '../../utils/is-ci';
+import { createTerminalUI } from '../../utils/terminal-ui';
+import { formatTelemetryStatusLines, resolveTelemetryStatus } from './status';
+
+function createTelemetryStatusCommand(): Command {
+  const command = new Command('status');
+  setCommandDescriptions(
+    command,
+    'Show whether anonymous CLI telemetry is enabled and why',
+    'Reports whether telemetry is currently enabled or disabled and the reason\n' +
+      '(default-on, stored opt-out, environment opt-out, or CI), the path to your\n' +
+      'user-level config file, and whether an installation ID has been stored.\n' +
+      'Read-only: never sends an event, never mints an ID, never writes anything.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    const ui = createTerminalUI(flags);
+    const status = resolveTelemetryStatus({ env: process.env, inCI: isCI() });
+    if (flags.json) {
+      ui.output(JSON.stringify(status));
+    } else {
+      for (const line of formatTelemetryStatusLines(status)) {
+        ui.output(line);
+      }
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryEnableCommand(): Command {
+  const command = new Command('enable');
+  setCommandDescriptions(
+    command,
+    'Enable anonymous CLI telemetry',
+    'Stores "enableTelemetry": true in your user-level config and mints an\n' +
+      'installation ID if one is not already stored.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: true });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: true, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry enabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+function createTelemetryDisableCommand(): Command {
+  const command = new Command('disable');
+  setCommandDescriptions(
+    command,
+    'Disable anonymous CLI telemetry',
+    'Stores "enableTelemetry": false in your user-level config. No installation\n' +
+      'ID is minted and no event is sent.',
+  );
+  return addGlobalOptions(command).action((options: CommonCommandOptions) => {
+    const flags = parseGlobalFlagsOrExit(options);
+    writeUserConfig({ enableTelemetry: false });
+    const ui = createTerminalUI(flags);
+    if (flags.json) {
+      ui.output(JSON.stringify({ enableTelemetry: false, configPath: userConfigPath() }));
+    } else {
+      ui.output(`Telemetry disabled. Preference stored in ${userConfigPath()}.`);
+    }
+    process.exit(0);
+  });
+}
+
+export function createTelemetryCommand(): Command {
+  const command = new Command('telemetry');
+  setCommandDescriptions(
+    command,
+    'Inspect and change anonymous CLI telemetry',
+    'Show telemetry status, or enable / disable anonymous CLI usage data.\n' +
+      'Telemetry is on by default (opt-out); see https://prisma-next.dev/docs/cli/telemetry\n' +
+      'for what is collected and why.',
+  );
+  setCommandExamples(command, [
+    'prisma-next telemetry status',
+    'prisma-next telemetry disable',
+    'prisma-next telemetry enable',
+  ]);
+  command.configureHelp({
+    formatHelp: (cmd) => formatCommandHelp({ command: cmd, flags: parseGlobalFlags({}) }),
+    subcommandDescription: () => '',
+  });
+  command.addCommand(createTelemetryStatusCommand());
+  command.addCommand(createTelemetryEnableCommand());
+  command.addCommand(createTelemetryDisableCommand());
+  return command;
+}

package/src/commands/telemetry/status.ts

@@ -0,0 +1,67 @@
+import { readUserConfig, resolveGating, userConfigPath } from '@prisma-next/cli-telemetry';
+
+/**
+ * Why telemetry resolves the way it does, in the order the CLI's
+ * `resolveTelemetryGate` evaluates: CI hard-disables first, then the env
+ * opt-outs, then the stored `enableTelemetry`, then the opt-out default.
+ */
+export type TelemetryStatusReason =
+  | 'ci'
+  | 'env-opt-out'
+  | 'stored-opt-out'
+  | 'stored-opt-in'
+  | 'default-on';
+
+export interface TelemetryStatus {
+  readonly enabled: boolean;
+  readonly reason: TelemetryStatusReason;
+  readonly configPath: string;
+  readonly installationIdStored: boolean;
+}
+
+/**
+ * Resolves the same gate the runtime uses (CI check + `resolveGating`) and
+ * projects it into a user-facing status. Pure read: never mints, never
+ * writes. The `installationId` value itself is never surfaced — only its
+ * presence — so `status` discloses nothing identifying.
+ */
+export function resolveTelemetryStatus(inputs: {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly inCI: boolean;
+}): TelemetryStatus {
+  const config = readUserConfig();
+  const configPath = userConfigPath();
+  const installationIdStored =
+    typeof config.installationId === 'string' && config.installationId.length > 0;
+
+  if (inputs.inCI) {
+    return { enabled: false, reason: 'ci', configPath, installationIdStored };
+  }
+
+  const gating = resolveGating({ env: inputs.env, config });
+  if (!gating.enabled) {
+    const reason: TelemetryStatusReason =
+      gating.reason === 'env-override' ? 'env-opt-out' : 'stored-opt-out';
+    return { enabled: false, reason, configPath, installationIdStored };
+  }
+
+  const reason: TelemetryStatusReason =
+    config.enableTelemetry === true ? 'stored-opt-in' : 'default-on';
+  return { enabled: true, reason, configPath, installationIdStored };
+}
+
+const REASON_EXPLANATION: Record<TelemetryStatusReason, string> = {
+  ci: 'CI environment detected — telemetry is hard-disabled.',
+  'env-opt-out': 'an environment opt-out is set (DO_NOT_TRACK / PRISMA_NEXT_DISABLE_TELEMETRY).',
+  'stored-opt-out': '"enableTelemetry": false is stored in your config.',
+  'stored-opt-in': '"enableTelemetry": true is stored in your config.',
+  'default-on': 'no explicit choice is stored, so the opt-out default applies.',
+};
+
+export function formatTelemetryStatusLines(status: TelemetryStatus): string[] {
+  return [
+    `Telemetry is ${status.enabled ? 'enabled' : 'disabled'}: ${REASON_EXPLANATION[status.reason]}`,
+    `Config file: ${status.configPath}`,
+    `Installation ID: ${status.installationIdStored ? 'stored' : 'not stored'}`,
+  ];
+}

package/src/control-api/client.ts

@@ -1,4 +1,8 @@
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import { emit as emitContractArtifacts } from '@prisma-next/emitter';
 import type { TargetBoundComponentDescriptor } from '@prisma-next/framework-components/components';
 import type {
@@ -447,6 +451,12 @@ class ControlClientImpl implements ControlClient {
     return familyInstance.readAllMarkers({ driver });
   }
 
+  /** Reads the per-migration journal; omit `space` to return every space. */
+  async readLedger(space?: string): Promise<readonly LedgerEntryRecord[]> {
+    const { driver, familyInstance } = await this.ensureConnected();
+    return familyInstance.readLedger({ driver, ...ifDefined('space', space) });
+  }
+
   async migrationApply(options: MigrationApplyOptions): Promise<MigrationApplyResult> {
     const { onProgress } = options;
     await this.connectWithProgress(options.connection, 'migrationApply', onProgress);

package/src/control-api/operations/apply.ts

@@ -141,6 +141,7 @@ export async function applyMigration<TFamilyId extends string, TTargetId extends
     destinationContract: r.entry.destinationContract,
     policy,
     frameworkComponents,
+    migrationEdges: r.entry.migrationEdges,
     // Per-space post-apply schema verification is non-strict: each
     // space's `destinationContract` describes only its own slice; a
     // strict verifier would treat every other space's tables as

package/src/control-api/operations/db-apply.ts

@@ -5,6 +5,7 @@ import type {
   ControlExtensionDescriptor,
   ControlFamilyInstance,
   MigrationOperationPolicy,
+  MigrationPlannerConflict,
   MigrationPlanOperation,
   OperationPreview,
   TargetMigrationsCapability,
@@ -32,7 +33,12 @@ import type {
   OnControlProgress,
   PerSpaceExecutionEntry,
 } from '../types';
-import { applyMigration, buildPerSpaceBreakdown, collectOrdered } from './apply';
+import {
+  applyMigration,
+  buildPerSpaceBreakdown,
+  collectOrdered,
+  type OrderedResolution,
+} from './apply';
 import { stripOperations } from './migration-helpers';
 
 /**
@@ -175,6 +181,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
   onProgress?.({ action, kind: 'spanEnd', spanId: SPAN_IDS.plan, outcome: 'ok' });
 
   const orderedResolutions = collectOrdered(planResult.value.applyOrder, planResult.value.perSpace);
+  const plannerWarnings = aggregatePlannerWarnings(orderedResolutions);
 
   // The destination's structural shape comes from the app's plan — its
   // `destination` is the storage hash users see in CLI output.
@@ -202,6 +209,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       preview,
       perSpace,
       summary,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
@@ -228,6 +236,7 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
       summary: applied.failure.summary,
       ...ifDefined('why', applied.failure.why),
       meta: applied.failure.meta,
+      ...ifDefined('warnings', plannerWarnings),
     });
   }
 
@@ -246,9 +255,17 @@ export async function executeApply<TFamilyId extends string, TTargetId extends s
     operationsExecuted: applied.value.totalOpsExecuted,
     perSpace: applied.value.perSpace,
     summary,
+    ...ifDefined('warnings', plannerWarnings),
   });
 }
 
+function aggregatePlannerWarnings(
+  orderedResolutions: readonly OrderedResolution[],
+): readonly MigrationPlannerConflict[] | undefined {
+  const warnings = orderedResolutions.flatMap((r) => r.entry.warnings ?? []);
+  return warnings.length > 0 ? warnings : undefined;
+}
+
 /**
  * Compare the live `_prisma_marker` rows against the aggregate's
  * declared members. Any marker row whose `space` is not a member of
@@ -339,6 +356,7 @@ function wrapPlanResult(args: {
   readonly preview: OperationPreview | undefined;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'plan',
@@ -352,6 +370,7 @@ function wrapPlanResult(args: {
     },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -363,6 +382,7 @@ function wrapApplyResult(args: {
   readonly operationsExecuted: number;
   readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly summary: string;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const success: DbInitSuccess | DbUpdateSuccess = {
     mode: 'apply',
@@ -380,6 +400,7 @@ function wrapApplyResult(args: {
       : { storageHash: args.destination.storageHash },
     perSpace: args.perSpace,
     summary: args.summary,
+    ...ifDefined('warnings', args.warnings),
   };
   return ok(success);
 }
@@ -388,6 +409,7 @@ function buildRunnerFailure(args: {
   readonly summary: string;
   readonly why?: string;
   readonly meta: Record<string, unknown>;
+  readonly warnings?: readonly MigrationPlannerConflict[];
 }): DbInitResult | DbUpdateResult {
   const failure: DbInitFailure | DbUpdateFailure = {
     code: 'RUNNER_FAILED',
@@ -395,6 +417,7 @@ function buildRunnerFailure(args: {
     why: args.why,
     meta: args.meta,
     conflicts: undefined,
+    ...ifDefined('warnings', args.warnings),
   };
   return notOk(failure) as DbInitResult | DbUpdateResult;
 }

package/src/control-api/operations/migration-apply.ts

@@ -7,6 +7,7 @@ import type {
   TargetMigrationsCapability,
 } from '@prisma-next/framework-components/control';
 import {
+  buildSynthMigrationEdge,
   type ContractMarkerRecordLike,
   type ContractSpaceAggregate,
   type ContractSpaceMember,
@@ -319,7 +320,7 @@ export async function executeMigrationApply<TFamilyId extends string, TTargetId
     includeMarkers: true,
   });
   const totalMigrationsApplied = applied.value.orderedResolutions.reduce(
-    (sum, r) => sum + (r.entry.migrationEdges?.length ?? 0),
+    (sum, r) => sum + r.entry.migrationEdges.length,
     0,
   );
   const summary = `Applied ${totalMigrationsApplied} migration(s) (${applied.value.totalOpsExecuted} operation(s)) across ${orderedAll.length} contract space(s)`;
@@ -361,7 +362,13 @@ function buildAtHeadResolution(args: {
     displayOps: [],
     destinationContract: member.contract(),
     strategy: 'graph-walk',
-    migrationEdges: [],
+    migrationEdges: [
+      buildSynthMigrationEdge({
+        currentMarkerStorageHash: liveMarker?.storageHash,
+        destinationStorageHash: targetHash,
+        operationCount: 0,
+      }),
+    ],
   };
 }
 
@@ -404,7 +411,7 @@ function buildSuccess(args: BuildSuccessArgs): MigrationApplySuccess {
   // JSON-shape consumers (e.g. `parsed.applied.length` in integration
   // tests). The aggregate per-space breakdown lives on `perSpace[]`.
   const applied = args.orderedResolutions.flatMap((r) => {
-    const edges = r.entry.migrationEdges ?? [];
+    const edges = r.entry.migrationEdges;
     return edges.map((edge) => ({
       spaceId: r.spaceId,
       dirName: edge.dirName,

package/src/control-api/types.ts

@@ -2,7 +2,11 @@ import type {
   ContractSourceDiagnostics,
   ContractSourceProvider,
 } from '@prisma-next/config/config-types';
-import type { Contract, ContractMarkerRecord } from '@prisma-next/contract/types';
+import type {
+  Contract,
+  ContractMarkerRecord,
+  LedgerEntryRecord,
+} from '@prisma-next/contract/types';
 import type {
   ControlAdapterDescriptor,
   ControlDriverDescriptor,
@@ -391,6 +395,7 @@ export interface DbInitSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -406,6 +411,7 @@ export interface DbInitFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
   readonly marker?: {
     readonly storageHash?: string;
@@ -461,6 +467,7 @@ export interface DbUpdateSuccess {
    */
   readonly perSpace?: ReadonlyArray<PerSpaceExecutionEntry>;
   readonly summary: string;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
 }
 
 /**
@@ -476,6 +483,7 @@ export interface DbUpdateFailure {
   readonly summary: string;
   readonly why: string | undefined;
   readonly conflicts: ReadonlyArray<MigrationPlannerConflict> | undefined;
+  readonly warnings?: ReadonlyArray<MigrationPlannerConflict>;
   readonly meta: Record<string, unknown> | undefined;
 }
 
@@ -876,6 +884,13 @@ export interface ControlClient {
    */
   readAllMarkers(): Promise<ReadonlyMap<string, ContractMarkerRecord>>;
 
+  /**
+   * Reads the per-migration ledger journal for `space` in apply order.
+   * Returns an empty array when the ledger store does not yet exist or
+   * has no rows for that space.
+   */
+  readLedger(space?: string): Promise<readonly LedgerEntryRecord[]>;
+
   /**
    * Applies pre-planned on-disk migrations to the database.
    * Each migration runs in its own transaction with full execution checks.

package/src/utils/cli-errors.ts

@@ -108,6 +108,23 @@ export function errorRefSetEmptySentinel(hash: string): CliStructuredError {
   });
 }
 
+/**
+ * `--legend` was combined with a machine-readable or silent output flag.
+ * The legend is human-only decoration on stderr.
+ */
+export function errorLegendHumanOnly(
+  conflictingFlag: '--json' | '--dot' | '--quiet',
+): CliStructuredError {
+  return errorRuntime('`--legend` is only available for human-readable output', {
+    why: `\`--legend\` prints a glyph key to stderr and cannot be combined with ${conflictingFlag}.`,
+    fix: `Omit ${conflictingFlag} to print the legend alongside the tree, or omit --legend when using ${conflictingFlag}.`,
+    meta: {
+      code: 'MIGRATION.LEGEND_HUMAN_ONLY',
+      conflictingFlag,
+    },
+  });
+}
+
 /**
  * `--space <id>` was given a value that doesn't satisfy the contract-space
  * naming rule (`[a-z][a-z0-9_-]{0,63}` per `isValidSpaceId`). Fires before

package/src/utils/formatters/errors.ts

@@ -1,8 +1,11 @@
+import type { MigrationPlannerConflict } from '@prisma-next/framework-components/control';
+import { blindCast } from '@prisma-next/utils/casts';
 import { red } from 'colorette';
 
 import type { CliErrorConflict, CliErrorEnvelope } from '../cli-errors';
 import type { GlobalFlags } from '../global-flags';
 import { createColorFormatter, formatDim, isVerbose } from './helpers';
+import { formatPlannerWarningsBlock } from './migrations';
 
 /**
  * Formats error output for human-readable display.
@@ -67,6 +70,14 @@ export function formatErrorOutput(error: CliErrorEnvelope, flags: GlobalFlags):
   if (error.docsUrl && isVerbose(flags, 1)) {
     lines.push(formatDimText(error.docsUrl));
   }
+  const plannerWarnings = error.meta?.['plannerWarnings'];
+  if (Array.isArray(plannerWarnings) && plannerWarnings.length > 0) {
+    const typedWarnings = blindCast<
+      readonly MigrationPlannerConflict[],
+      'mapDbUpdateFailure (db-update.ts) writes meta.plannerWarnings as MigrationPlannerConflict[]; meta is typed Record<string, unknown> so the channel erases the element type'
+    >(plannerWarnings);
+    lines.push(...formatPlannerWarningsBlock(typedWarnings, useColor));
+  }
   if (isVerbose(flags, 2) && error.meta) {
     lines.push(`${formatDimText(`  Meta: ${JSON.stringify(error.meta, null, 2)}`)}`);
   }

package/src/utils/formatters/migration-graph-lane-colors.ts

@@ -0,0 +1,194 @@
+import { createColors } from 'colorette';
+import type { StructuralCell } from './migration-graph-layout';
+
+export type LaneColorizer = (text: string) => string;
+
+const { magenta, cyan, green, yellow, blueBright, red } = createColors({ useColor: true });
+
+export const LANE_COLOR_CYCLE: readonly LaneColorizer[] = [
+  magenta,
+  cyan,
+  green,
+  yellow,
+  blueBright,
+  red,
+];
+
+/**
+ * The leftmost lane (column 0) renders neutral — no palette hue. Columns ≥ 1
+ * rotate through {@link LANE_COLOR_CYCLE}.
+ */
+export const NEUTRAL_LANE_COLUMN = 0;
+
+/**
+ * The hue for a gutter column. The leftmost lane (column 0) is **neutral** — it
+ * has nothing to be told apart from in the common single-lane linear case, so
+ * the renderer dims it rather than tinting it; the rotating palette is reserved
+ * for columns ≥ 1 (where a second lane exists to distinguish). Callers must dim
+ * column 0 themselves; this returns identity for it as a guard. A lane freed and
+ * reused by a later branch keeps its column's hue — coloring is by position, not
+ * branch identity, exactly like `git log --graph`.
+ */
+export function laneColorForColumn(column: number): LaneColorizer {
+  if (column <= NEUTRAL_LANE_COLUMN) {
+    return (text) => text;
+  }
+  const colorizer = LANE_COLOR_CYCLE[(column - 1) % LANE_COLOR_CYCLE.length];
+  return colorizer ?? ((text) => text);
+}
+
+/**
+ * Style a structural glyph by its resolved colour column. Column 0 and the
+ * neutral sentinel render dim (`dimLane`); columns ≥ 1 take a palette hue.
+ */
+export function stylerForLaneColumn(
+  colorColumn: number,
+  colorize: boolean,
+  dimLane: (text: string) => string,
+): LaneColorizer {
+  if (!colorize || colorColumn <= NEUTRAL_LANE_COLUMN) {
+    return dimLane;
+  }
+  return laneColorForColumn(colorColumn);
+}
+
+/**
+ * The colour-source column for each cell of a row, resolved together because a
+ * routed back-arc spans columns and must read as **one hue** rather than a
+ * per-column "rainbow".
+ */
+export interface RowArcLaneColors {
+  /** Colour column for a cell's structural glyph (lane / spine / arc body). */
+  readonly lane: readonly number[];
+  /** Colour column for a node arc-pair's connector half (`◂` / `─`). */
+  readonly connector: readonly number[];
+  /**
+   * Colour column for the trailing `─` of a landing tee (`┴─`). The junction
+   * (`lane`) keeps its own column; the dash leads into the next converging arc.
+   */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell colour columns for a node/arc row. Scanning right-to-left
+ * lets each arc segment inherit the hue of the arc it leads into.
+ */
+export function resolveRowArcLaneColors(cells: readonly StructuralCell[]): RowArcLaneColors {
+  const lane = new Array<number>(cells.length);
+  const connector = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let arcCorner = NEUTRAL_LANE_COLUMN;
+  let landingAnchor = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    connector[column] = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+    switch (cell?.kind) {
+      case 'arc-branch-corner':
+        arcCorner = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-corner':
+        arcCorner = column;
+        landingAnchor = column;
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-branch-tee':
+        lane[column] = column;
+        dash[column] = column;
+        break;
+      case 'arc-land-tee':
+        lane[column] = column;
+        dash[column] = landingAnchor === NEUTRAL_LANE_COLUMN ? column : landingAnchor;
+        landingAnchor = column;
+        break;
+      case 'arc-crossing':
+      case 'arc-land-bridge': {
+        const served = landingAnchor !== NEUTRAL_LANE_COLUMN ? landingAnchor : arcCorner;
+        lane[column] = served;
+        dash[column] = served;
+        break;
+      }
+      case 'horizontal-pass':
+        lane[column] = arcCorner === NEUTRAL_LANE_COLUMN ? column : arcCorner;
+        dash[column] = lane[column] ?? column;
+        break;
+      case 'node':
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+        break;
+      default:
+        lane[column] = column;
+        dash[column] = column;
+        arcCorner = NEUTRAL_LANE_COLUMN;
+        landingAnchor = NEUTRAL_LANE_COLUMN;
+    }
+  }
+  return { lane, connector, dash };
+}
+
+/**
+ * Per-cell colour for a forward branch/merge connector row, split into the
+ * cell's junction `glyph` and its trailing `dash`.
+ */
+export interface ConnectorLaneColors {
+  /** Colour column for a cell's junction glyph (`├` / `┬` / `┴` / `╮` / `╯`). */
+  readonly glyph: readonly number[];
+  /** Colour column for a tee's trailing `─` — the branch it leads into. */
+  readonly dash: readonly number[];
+}
+
+/**
+ * Resolve per-cell connector colours. Scanning right-to-left, a corner or an
+ * intermediate tee anchors its own lane, but a tee's trailing dash leads into
+ * the branch on its right.
+ */
+export function resolveConnectorLaneColors(
+  cells: readonly StructuralCell[],
+  startLane: number,
+): ConnectorLaneColors {
+  const glyph = new Array<number>(cells.length);
+  const dash = new Array<number>(cells.length);
+  let owner = NEUTRAL_LANE_COLUMN;
+  for (let column = cells.length - 1; column >= 0; column--) {
+    const cell = cells[column];
+    switch (cell?.kind) {
+      case 'branch-corner':
+      case 'merge-corner':
+        owner = column;
+        glyph[column] = column;
+        dash[column] = column;
+        break;
+      case 'branch-tee':
+      case 'merge-tee':
+        if (column === startLane) {
+          const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          dash[column] = served;
+        } else {
+          dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+          glyph[column] = column;
+          owner = column;
+        }
+        break;
+      case 'arc-crossing':
+        glyph[column] = column;
+        dash[column] = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        owner = column;
+        break;
+      case 'horizontal-pass': {
+        const served = owner === NEUTRAL_LANE_COLUMN ? column : owner;
+        glyph[column] = served;
+        dash[column] = served;
+        break;
+      }
+      default:
+        glyph[column] = column;
+        dash[column] = column;
+    }
+  }
+  return { glyph, dash };
+}