@workbench-kit/field-remap 0.0.2-prototype.0.2.26 → 0.0.2-prototype.0.2.28

package/README.md

@@ -60,9 +60,10 @@ a lighter mapping detail rail (chain overview, palette, list context).
 
 ### Shape ownership
 
-`FieldRemapDocument` (v1) stores **edges only**. Hosts own input/output shapes
-(`SourceField[]` / `TargetSlot[]`, or `defineDataShape` + ingest helpers) and pass
-them into `convertToShape` / the shell `FieldRemapPanel` / `FieldRemapFlowMapper`.
+`FieldRemapDocument` stores edges plus optional combine/split operators. Hosts own
+input/output shapes (`SourceField[]` / `TargetSlot[]`, or `defineDataShape` + ingest
+helpers) and pass them into `convertToShape` / the shell `FieldRemapPanel` /
+`FieldRemapFlowMapper`.
 Optional `classRef` / `hidden` on fields and slots are additive; use
 `projectShapes` / `projectSourceFields` / `projectTargetSlots` with
 `includeHidden` (default omit hidden) before wiring Flow columns, and
@@ -119,7 +120,7 @@ build `defineConversion` / `defineDataShape` registries yourself.
 Place-then-wire uses **ephemeral draft nodes** in the shell Flow UI: place a
 transform, wire source then target (or the reverse), and the draft finalizes into
 a `MappingEdge` with `transformIds: [id]`. Escape discards unfinished drafts.
-The persisted document stays edges-only — no free graph. You can also add steps
+The persisted document stays mapping-only — no free graph nodes. You can also add steps
 via the detail palette / `+ node` onto an existing binding (max 3). List context
 uses `itemEdges` on array→array bindings.
 
@@ -135,13 +136,13 @@ uses `itemEdges` on array→array bindings.
 
 ### n→m operators (combine / split)
 
-`FieldRemapDocument` **v1** is edges-only (1→1 bindings). **v2** (current) adds an
-optional `operators[]` list for fan-in / fan-out. Call `applyMappingOperators` with
+`FieldRemapDocument` v2 includes an optional `operators[]` list for fan-in / fan-out.
+Call `applyMappingOperators` with
 `combine` / `split` operators (limits: `MAX_MAPPING_FAN_IN` / `MAX_MAPPING_FAN_OUT`
 = 8). Hosts may merge the result with `convertToShape` output.
-`migrateFieldRemapDocument` / `parseFieldRemapDocument` accept v1 and v2 and always
-emit the current version. Shell Flow renders combine/split as multi-port nodes and
-supports authoring (create / wire ports / delete) when hosts pass `operators` +
+`parseFieldRemapDocument` accepts the current version and normalizes edges and operators.
+Shell Flow renders combine/split as multi-port nodes and supports authoring
+(create / wire ports / delete) when hosts pass `operators` +
 `onOperatorsChange` into `FieldRemapFlowMapper` (sample `nm-combine-split`).
 
 ```ts
@@ -269,8 +270,8 @@ Pass `signal` on `convertToShape` (or `TransformContext.signal`) to cancel stale
 Aborted runs reject with `AbortError` and stop further edges / chain steps. The shell Field Remap
 panel wires an `AbortController` to effect cleanup.
 
-Host JSONata transforms in `@workbench-kit/shell-react` are bounded by default (`timeoutMs`,
-`maxExpressionLength`, `onError: 'throw'`). Use `createJsonataValueTransform()` to override.
+Host JSONata transforms in `@workbench-kit/shell-react` are fail-closed and bounded by default
+(`timeoutMs`, `maxExpressionLength`). Use `createJsonataValueTransform()` to override the bounds.
 
 ## Layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workbench-kit/field-remap",
-  "version": "0.0.2-prototype.0.2.26",
+  "version": "0.0.2-prototype.0.2.28",
   "private": false,
   "type": "module",
   "exports": {

package/src/domain/constants.ts

@@ -3,12 +3,3 @@ export const MAX_TRANSFORM_CHAIN = 3;
 
 /** Built-in pass-through transform id (kept here to avoid import cycles). */
 export const IDENTITY_TRANSFORM_ID = 'identity';
-
-/** Legacy id aliases → canonical ids (empty until hosts need migration). */
-export const TRANSFORM_ID_ALIASES: Readonly<Record<string, string>> = {};
-
-/** Map a legacy or canonical transform id to its canonical form. */
-export function canonicalizeTransformId(id: string): string {
-  const trimmed = id.trim();
-  return TRANSFORM_ID_ALIASES[trimmed] ?? trimmed;
-}

package/src/domain/document/fieldRemapDocument.ts

@@ -4,20 +4,15 @@ import type { MappingEdge, MappingOperator, FieldRemapDocument } from '../types.
 
 /** Current persistence version (edges + optional `operators[]`). */
 export const FIELD_REMAP_DOCUMENT_VERSION = 2 as const;
-/** Legacy edges-only documents. */
-export const FIELD_REMAP_DOCUMENT_V1_VERSION = 1 as const;
 
-type SupportedDocumentVersion =
-  typeof FIELD_REMAP_DOCUMENT_VERSION | typeof FIELD_REMAP_DOCUMENT_V1_VERSION;
-
-/** Thrown when parse/deserialize sees a document `version` other than a supported constant. */
+/** Thrown when parse/deserialize sees a document `version` other than the current constant. */
 export class UnsupportedFieldRemapDocumentVersionError extends Error {
   readonly version: unknown;
   readonly expectedVersion: typeof FIELD_REMAP_DOCUMENT_VERSION;
 
   constructor(version: unknown) {
     super(
-      `Unsupported field remap document version ${String(version)}; expected ${FIELD_REMAP_DOCUMENT_V1_VERSION} or ${FIELD_REMAP_DOCUMENT_VERSION}.`,
+      `Unsupported field remap document version ${String(version)}; expected ${FIELD_REMAP_DOCUMENT_VERSION}.`,
     );
     this.name = 'UnsupportedFieldRemapDocumentVersionError';
     this.version = version;
@@ -50,13 +45,9 @@ export function createFieldRemapDocument(
   };
 }
 
-function isSupportedVersion(version: unknown): version is SupportedDocumentVersion {
-  return version === FIELD_REMAP_DOCUMENT_V1_VERSION || version === FIELD_REMAP_DOCUMENT_VERSION;
-}
-
-/** Normalize edges / operators on a persisted document; always emits the current version. */
+/** Normalize edges / operators on a current persisted document. */
 export function normalizeFieldRemapDocument(document: FieldRemapDocument): FieldRemapDocument {
-  if (!isSupportedVersion(document.version)) {
+  if (document.version !== FIELD_REMAP_DOCUMENT_VERSION) {
     throw new UnsupportedFieldRemapDocumentVersionError(document.version);
   }
   const operators = normalizeMappingOperators(document.operators);
@@ -83,8 +74,7 @@ export function serializeFieldRemapDocument(
 }
 
 /**
- * Parse an unknown JSON value into a normalized `FieldRemapDocument`.
- * Accepts v1 (edges-only) and v2 (optional operators); always returns current version.
+ * Parse an unknown JSON value into a normalized current `FieldRemapDocument`.
  */
 export function parseFieldRemapDocument(input: unknown): FieldRemapDocument {
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -97,7 +87,7 @@ export function parseFieldRemapDocument(input: unknown): FieldRemapDocument {
   if (!('version' in record)) {
     throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
   }
-  if (!isSupportedVersion(record.version)) {
+  if (record.version !== FIELD_REMAP_DOCUMENT_VERSION) {
     throw new UnsupportedFieldRemapDocumentVersionError(record.version);
   }
   if (!Array.isArray(record.edges)) {
@@ -114,7 +104,7 @@ export function parseFieldRemapDocument(input: unknown): FieldRemapDocument {
   }
 
   return normalizeFieldRemapDocument({
-    version: record.version,
+    version: FIELD_REMAP_DOCUMENT_VERSION,
     edges: record.edges as MappingEdge[],
     operators: record.operators as MappingOperator[] | undefined,
   });
@@ -131,33 +121,3 @@ export function deserializeFieldRemapDocument(json: string): FieldRemapDocument
   }
   return parseFieldRemapDocument(parsed);
 }
-
-/**
- * Migrate an unknown persisted value to the current {@link FieldRemapDocument}.
- *
- * Hosts should call this (or `parseFieldRemapDocument`) at load time so future
- * document versions can be rewritten here without changing call sites.
- *
- * **v1:** edges-only → current version (operators omitted).
- * **v2:** normalize edges + operators.
- */
-export function migrateFieldRemapDocument(input: unknown): FieldRemapDocument {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new InvalidFieldRemapDocumentError(
-      'Expected a field remap document object with version and edges.',
-    );
-  }
-
-  const record = input as Record<string, unknown>;
-  if (!('version' in record)) {
-    throw new InvalidFieldRemapDocumentError('Field remap document is missing version.');
-  }
-
-  switch (record.version) {
-    case FIELD_REMAP_DOCUMENT_V1_VERSION:
-    case FIELD_REMAP_DOCUMENT_VERSION:
-      return parseFieldRemapDocument(input);
-    default:
-      throw new UnsupportedFieldRemapDocumentVersionError(record.version);
-  }
-}

package/src/domain/document/mappingEdge.ts

@@ -1,20 +1,12 @@
-import {
-  canonicalizeTransformId,
-  IDENTITY_TRANSFORM_ID,
-  MAX_TRANSFORM_CHAIN,
-} from '../constants.js';
-import {
-  sanitizeOptionRecord,
-  sanitizeOptionSteps,
-  sharedOptionsFromSteps,
-} from '../mapping/transformOptions.js';
+import { IDENTITY_TRANSFORM_ID, MAX_TRANSFORM_CHAIN } from '../constants.js';
+import { sanitizeOptionSteps } from '../mapping/transformOptions.js';
 import type { MappingEdge } from '../types.js';
 
 export { MAX_TRANSFORM_CHAIN } from '../constants.js';
 
 function sanitizeTransformIds(ids: readonly string[] | undefined): string[] {
   const cleaned = ids
-    ?.map((id) => canonicalizeTransformId(id))
+    ?.map((id) => id.trim())
     .filter((id) => id.length > 0 && id !== IDENTITY_TRANSFORM_ID);
   if (!cleaned || cleaned.length === 0) {
     return [];
@@ -22,23 +14,9 @@ function sanitizeTransformIds(ids: readonly string[] | undefined): string[] {
   return cleaned.slice(0, MAX_TRANSFORM_CHAIN);
 }
 
-/**
- * Resolve the effective transform chain for an edge.
- * Prefers `transformIds`; falls back to legacy `transformId`.
- * Identity / empty / null → `[]` (pass-through).
- */
+/** Resolve the effective transform chain for an edge. Identity / empty → pass-through. */
 export function edgeTransformIds(edge: MappingEdge): string[] {
-  const fromList = sanitizeTransformIds(edge.transformIds);
-  if (fromList.length > 0) {
-    return fromList;
-  }
-
-  const legacy = edge.transformId ? canonicalizeTransformId(edge.transformId) : '';
-  if (legacy && legacy !== IDENTITY_TRANSFORM_ID) {
-    return [legacy];
-  }
-
-  return [];
+  return sanitizeTransformIds(edge.transformIds);
 }
 
 /** Per-item transform chain applied after optional `itemSourcePath` projection. */
@@ -46,15 +24,7 @@ export function edgeItemTransformIds(edge: MappingEdge): string[] {
   return sanitizeTransformIds(edge.itemTransformIds);
 }
 
-/**
- * Normalize an edge to the `transformIds` model while keeping `transformId`
- * as the first chain step (or `null`) for older hosts.
- *
- * Option bags:
- * - Prefer `transformOptionSteps` when present (aligned to chain length).
- * - Keep `transformOptions` as the first non-empty step (or the legacy shared bag).
- * - Same rules for `itemTransformOptionSteps` / `itemTransformOptions`.
- */
+/** Normalize transform chains and their aligned per-step option bags. */
 export function normalizeMappingEdge(edge: MappingEdge): MappingEdge {
   const ids = edgeTransformIds(edge);
   const itemIds = edgeItemTransformIds(edge);
@@ -69,29 +39,20 @@ export function normalizeMappingEdge(edge: MappingEdge): MappingEdge {
       : undefined;
 
   const transformOptionSteps = sanitizeOptionSteps(edge.transformOptionSteps, ids.length);
-  const transformOptions =
-    sharedOptionsFromSteps(transformOptionSteps) ?? sanitizeOptionRecord(edge.transformOptions);
-
   const itemTransformOptionSteps = sanitizeOptionSteps(
     edge.itemTransformOptionSteps,
     itemIds.length,
   );
-  const itemTransformOptions =
-    sharedOptionsFromSteps(itemTransformOptionSteps) ??
-    sanitizeOptionRecord(edge.itemTransformOptions);
 
   return {
     id: edge.id,
     sourceFieldId: edge.sourceFieldId,
     targetSlotId: edge.targetSlotId,
     transformIds: ids.length > 0 ? ids : undefined,
-    transformId: ids[0] ?? null,
     ...(transformOptionSteps ? { transformOptionSteps } : {}),
-    ...(transformOptions ? { transformOptions } : {}),
     ...(itemSourcePath && !itemEdges ? { itemSourcePath } : {}),
     ...(itemIds.length > 0 && !itemEdges ? { itemTransformIds: itemIds } : {}),
     ...(itemTransformOptionSteps && !itemEdges ? { itemTransformOptionSteps } : {}),
-    ...(itemTransformOptions && !itemEdges ? { itemTransformOptions } : {}),
     ...(itemEdges ? { itemEdges } : {}),
   };
 }
@@ -106,16 +67,12 @@ export function createMappingEdge(input: {
   readonly sourceFieldId: string;
   readonly targetSlotId: string;
   readonly transformIds?: readonly string[];
-  /** Legacy single id; ignored when `transformIds` is provided. */
-  readonly transformId?: string | null;
   readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  readonly transformOptions?: Readonly<Record<string, unknown>>;
   /** Optional per-item projection path for array mappings. */
   readonly itemSourcePath?: string;
   /** Optional per-item transform chain after projection. */
   readonly itemTransformIds?: readonly string[];
   readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
   /** List-context child edges for array-of-object → array-of-object. */
   readonly itemEdges?: readonly MappingEdge[];
 }): MappingEdge {
@@ -124,13 +81,10 @@ export function createMappingEdge(input: {
     sourceFieldId: input.sourceFieldId,
     targetSlotId: input.targetSlotId,
     transformIds: input.transformIds,
-    transformId: input.transformId,
     transformOptionSteps: input.transformOptionSteps,
-    transformOptions: input.transformOptions,
     itemSourcePath: input.itemSourcePath,
     itemTransformIds: input.itemTransformIds,
     itemTransformOptionSteps: input.itemTransformOptionSteps,
-    itemTransformOptions: input.itemTransformOptions,
     itemEdges: input.itemEdges,
   });
 }

package/src/domain/mapping/convertItemEdges.ts

@@ -75,7 +75,7 @@ export async function convertArrayWithItemEdges(input: {
             ? await identity.apply(sourceValue, { ...input.context, sampleValue: sourceValue })
             : sourceValue;
         } else {
-          const steps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
+          const steps = resolveOptionSteps(chain, edge.transformOptionSteps);
           value = await applyTransformChain(
             input.transforms,
             chain,

package/src/domain/mapping/mappingOperators.ts

@@ -4,11 +4,7 @@
  * {@link applyMappingOperators} explicitly without persisting.
  */
 
-import {
-  canonicalizeTransformId,
-  IDENTITY_TRANSFORM_ID,
-  MAX_TRANSFORM_CHAIN,
-} from '../constants.js';
+import { IDENTITY_TRANSFORM_ID, MAX_TRANSFORM_CHAIN } from '../constants.js';
 import { throwIfAborted } from '../abort.js';
 import type {
   CombineMappingOperator,
@@ -113,7 +109,7 @@ function readFieldValue(field: SourceField, inputs: Readonly<Record<string, unkn
 
 function sanitizeOperatorTransformIds(ids: readonly string[] | undefined): string[] | undefined {
   const cleaned = ids
-    ?.map((id) => canonicalizeTransformId(id))
+    ?.map((id) => id.trim())
     .filter((id) => id.length > 0 && id !== IDENTITY_TRANSFORM_ID);
   if (!cleaned || cleaned.length === 0) {
     return undefined;

package/src/domain/mapping/objectPathSafety.ts

@@ -103,21 +103,6 @@ export function parseObjectPath(path: string): ObjectPathSegment[] {
   });
 }
 
-/**
- * Parse dotted path segments as plain property names (no `[index]` / `[*]`).
- * Rejects unsafe segments when any parts exist.
- */
-export function requireObjectPathParts(path: string): string[] {
-  const segments = parseObjectPath(path);
-  if (segments.some((segment) => segment.kind !== 'property')) {
-    throw new InvalidObjectPathError(
-      path,
-      'index/wildcard segments are not allowed in this context',
-    );
-  }
-  return segments.map((segment) => segment.name);
-}
-
 export function isSafeObjectPath(path: string): boolean {
   const trimmed = path.trim();
   if (!SAFE_PATH_RE.test(trimmed)) {

package/src/domain/mapping/resolveMappedValue.ts

@@ -28,10 +28,9 @@ export function findSourceField(
  * Apply order:
  * 1. Optional `itemSourcePath` projection (array of objects → projected array)
  * 2. Optional `itemTransformIds` per element (when the value is still an array)
- * 3. `transformIds` / legacy `transformId` on the whole value (including array reduces)
+ * 3. `transformIds` on the whole value (including array reduces)
  *
- * Per-step options (`transformOptionSteps` / `itemTransformOptionSteps`) win when
- * present; otherwise shared `transformOptions` / `itemTransformOptions` apply to all steps.
+ * Per-step options are aligned through `transformOptionSteps` / `itemTransformOptionSteps`.
  */
 export async function resolveMappedValue(
   edge: MappingEdge,
@@ -44,11 +43,7 @@ export async function resolveMappedValue(
     : sourceValue;
 
   const itemChain = edgeItemTransformIds(edge);
-  const itemSteps = resolveOptionSteps(
-    itemChain,
-    edge.itemTransformOptionSteps,
-    edge.itemTransformOptions,
-  );
+  const itemSteps = resolveOptionSteps(itemChain, edge.itemTransformOptionSteps);
 
   if (itemChain.length > 0 && Array.isArray(current)) {
     current = await Promise.all(
@@ -62,7 +57,7 @@ export async function resolveMappedValue(
     return identity ? await identity.apply(current, context) : current;
   }
 
-  const valueSteps = resolveOptionSteps(chain, edge.transformOptionSteps, edge.transformOptions);
+  const valueSteps = resolveOptionSteps(chain, edge.transformOptionSteps);
   return applyTransformChain(registry, chain, current, context, valueSteps);
 }
 

package/src/domain/mapping/transformOptions.ts

@@ -1,39 +1,4 @@
-import type { TransformContext, TransformOptionField, ValueTransformRegistry } from '../types.js';
-
-/** Merge edge-local options over host `context.options` (edge wins). */
-export function contextWithEdgeOptions(
-  context: TransformContext,
-  edgeOptions: Readonly<Record<string, unknown>> | undefined,
-): TransformContext {
-  if (!edgeOptions || Object.keys(edgeOptions).length === 0) {
-    return context;
-  }
-  return {
-    ...context,
-    options: {
-      ...context.options,
-      ...edgeOptions,
-    },
-  };
-}
-
-/** Collect unique `optionFields` declared by transforms in a chain (later ids win per key). */
-export function collectOptionFields(
-  registry: ValueTransformRegistry,
-  transformIds: readonly string[],
-): TransformOptionField[] {
-  const byKey = new Map<string, TransformOptionField>();
-  for (const id of transformIds) {
-    const fields = registry.get(id)?.optionFields;
-    if (!fields) {
-      continue;
-    }
-    for (const field of fields) {
-      byKey.set(field.key, field);
-    }
-  }
-  return [...byKey.values()];
-}
+import type { TransformOptionField, ValueTransformRegistry } from '../types.js';
 
 /** Option fields for a single chain step. */
 export function optionFieldsForStep(
@@ -63,17 +28,6 @@ export function sanitizeOptionRecord(
   return Object.keys(next).length > 0 ? next : undefined;
 }
 
-export function patchOptionRecord(
-  previous: Readonly<Record<string, unknown>> | undefined,
-  key: string,
-  value: unknown,
-): Readonly<Record<string, unknown>> | undefined {
-  return sanitizeOptionRecord({
-    ...previous,
-    [key]: value,
-  });
-}
-
 /**
  * Align / sanitize per-step option bags to `length`.
  * Returns `undefined` when every step is empty.
@@ -97,79 +51,16 @@ export function sanitizeOptionSteps(
   return any ? next : undefined;
 }
 
-/**
- * Resolve per-step options for a transform chain.
- * Prefers `steps`; otherwise expands shared `transformOptions` to every step (apply-to-all).
- */
+/** Resolve sanitized per-step options aligned to a transform chain. */
 export function resolveOptionSteps(
   transformIds: readonly string[],
   steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
-  shared: Readonly<Record<string, unknown>> | undefined,
 ): (Readonly<Record<string, unknown>> | undefined)[] {
   const length = transformIds.length;
   if (length === 0) {
     return [];
   }
-  if (steps && steps.length > 0) {
-    return Array.from({ length }, (_, index) => sanitizeOptionRecord(steps[index]));
-  }
-  const bag = sanitizeOptionRecord(shared);
-  if (!bag) {
-    return Array.from({ length }, () => undefined);
-  }
-  return Array.from({ length }, () => bag);
-}
-
-/** Back-compat summary: first non-empty step bag (else undefined). */
-export function sharedOptionsFromSteps(
-  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
-): Readonly<Record<string, unknown>> | undefined {
-  if (!steps) {
-    return undefined;
-  }
-  for (const step of steps) {
-    const sanitized = sanitizeOptionRecord(step);
-    if (sanitized) {
-      return sanitized;
-    }
-  }
-  return undefined;
-}
-
-/** Merge all step bags (later steps win) — useful for live format-sample chips. */
-export function mergeOptionSteps(
-  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
-): Readonly<Record<string, unknown>> | undefined {
-  if (!steps || steps.length === 0) {
-    return undefined;
-  }
-  const merged: Record<string, unknown> = {};
-  for (const step of steps) {
-    if (!step) {
-      continue;
-    }
-    Object.assign(merged, step);
-  }
-  return sanitizeOptionRecord(merged);
-}
-
-export function patchOptionStep(
-  steps: readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined,
-  length: number,
-  index: number,
-  key: string,
-  value: unknown,
-  sharedFallback?: Readonly<Record<string, unknown>>,
-): readonly (Readonly<Record<string, unknown>> | undefined)[] | undefined {
-  const base = resolveOptionSteps(
-    Array.from({ length }, () => ''),
-    steps,
-    sharedFallback,
-  );
-  const next = base.map((step, stepIndex) =>
-    stepIndex === index ? patchOptionRecord(step, key, value) : step,
-  );
-  return sanitizeOptionSteps(next, length);
+  return Array.from({ length }, (_, index) => sanitizeOptionRecord(steps?.[index]));
 }
 
 export function resizeOptionSteps(

package/src/domain/types.ts

@@ -81,28 +81,15 @@ export interface MappingEdge {
   readonly targetSlotId: string;
   /**
    * Ordered transform chain (max 3). Empty / omitted means identity.
-   * Prefer this over `transformId` for new writers.
    * For arrays: use reduce builtins (`array:join`, `array:first`, …) here after
    * optional item projection / item transforms.
    */
   readonly transformIds?: readonly string[];
-  /**
-   * Legacy single transform. Prefer `transformIds`.
-   * Readers should use `edgeTransformIds` / `normalizeMappingEdge`.
-   * `null` / omitted (with no `transformIds`) means identity (pass-through).
-   */
-  readonly transformId?: string | null;
   /**
    * Per-step options aligned with `transformIds` (index N applies to step N).
-   * Prefer this when steps need different bags (e.g. `showSeconds` then `maxLength`).
+   * Steps may use different bags (e.g. `showSeconds` then `maxLength`).
    */
   readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  /**
-   * Shared options for all `transformIds` steps (legacy / apply-to-all).
-   * Used when `transformOptionSteps` is omitted. Still written as a back-compat
-   * summary of step 0 (or the first non-empty step) by `normalizeMappingEdge`.
-   */
-  readonly transformOptions?: Readonly<Record<string, unknown>>;
   /**
    * When the source is an array of objects, optional dotted path into each item
    * (e.g. `name` or `meta.label`) before the value is written to the target.
@@ -120,11 +107,6 @@ export interface MappingEdge {
    * Per-step options aligned with `itemTransformIds`.
    */
   readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  /**
-   * Shared options for all `itemTransformIds` steps (legacy / apply-to-all).
-   * Independent of `transformOptions` / `transformOptionSteps`.
-   */
-  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
   /**
    * List-context child bindings (Stedi-style): when source is an array of objects,
    * each element is converted through these edges into a target item object.
@@ -161,16 +143,14 @@ export type MappingOperator = CombineMappingOperator | SplitMappingOperator;
 
 /**
  * Minimal JSON-serializable mapping document for host persistence.
- * Hosts own schema trees; this document stores the binding graph (and optional
- * n→m operators from document v2 onward).
+ * Hosts own schema trees; this document stores the binding graph and optional n→m operators.
  */
 export interface FieldRemapDocument {
-  /** `1` = edges-only; `2` = edges + optional `operators[]`. */
-  readonly version: 1 | 2;
+  readonly version: 2;
   readonly edges: readonly MappingEdge[];
   /**
-   * Optional n→m combine/split operators (document v2).
-   * Omitted / empty on v1 documents and on v2 hosts that only use 1→1 edges.
+   * Optional n→m combine/split operators.
+   * Omitted / empty on hosts that only use 1→1 edges.
    */
   readonly operators?: readonly MappingOperator[];
 }
@@ -223,8 +203,7 @@ export interface ValueTransformDefinition {
   /**
    * Data-driven option editors (mapped rows / convert panel).
    * Values are stored per step (`transformOptionSteps` / `itemTransformOptionSteps`)
-   * or as a shared bag (`transformOptions` / `itemTransformOptions`), or on host
-   * `TransformContext.options`.
+   * or on host `TransformContext.options`.
    */
   readonly optionFields?: readonly TransformOptionField[];
 }

package/src/index.ts

@@ -15,12 +15,7 @@ export type {
   ValueTransformRegistry,
 } from './domain/types.js';
 
-export {
-  canonicalizeTransformId,
-  IDENTITY_TRANSFORM_ID,
-  MAX_TRANSFORM_CHAIN,
-  TRANSFORM_ID_ALIASES,
-} from './domain/constants.js';
+export { IDENTITY_TRANSFORM_ID, MAX_TRANSFORM_CHAIN } from './domain/constants.js';
 
 export {
   createMappingEdge,
@@ -34,11 +29,9 @@ export {
   createFieldRemapDocument,
   deserializeFieldRemapDocument,
   InvalidFieldRemapDocumentError,
-  migrateFieldRemapDocument,
   normalizeFieldRemapDocument,
   parseFieldRemapDocument,
   FIELD_REMAP_DOCUMENT_VERSION,
-  FIELD_REMAP_DOCUMENT_V1_VERSION,
   serializeFieldRemapDocument,
   UnsupportedFieldRemapDocumentVersionError,
 } from './domain/document/fieldRemapDocument.js';
@@ -93,17 +86,11 @@ export type {
 } from './domain/mapping/mappingOperators.js';
 
 export {
-  collectOptionFields,
-  contextWithEdgeOptions,
-  mergeOptionSteps,
   optionFieldsForStep,
-  patchOptionRecord,
-  patchOptionStep,
   resolveOptionSteps,
   resizeOptionSteps,
   sanitizeOptionRecord,
   sanitizeOptionSteps,
-  sharedOptionsFromSteps,
 } from './domain/mapping/transformOptions.js';
 
 export {

package/src/registry/createValueTransformRegistry.ts

@@ -1,5 +1,5 @@
 import { throwIfAborted } from '../domain/abort.js';
-import { canonicalizeTransformId, MAX_TRANSFORM_CHAIN } from '../domain/constants.js';
+import { MAX_TRANSFORM_CHAIN } from '../domain/constants.js';
 import type {
   FieldDataType,
   TransformContext,
@@ -18,8 +18,7 @@ export function createValueTransformRegistry(
   }
 
   function resolve(id: string): ValueTransformDefinition | undefined {
-    const canonical = canonicalizeTransformId(id);
-    return byId.get(canonical) ?? byId.get(id);
+    return byId.get(id.trim()) ?? byId.get(id);
   }
 
   return {