@ubercode/dcmtk 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -2,18 +2,41 @@
 
 var path = require('path');
 var zod = require('zod');
-var fs = require('fs');
+var fs$1 = require('fs');
 var child_process = require('child_process');
 var kill = require('tree-kill');
 var events = require('events');
 var stderrLib = require('stderr-lib');
-var promises = require('fs/promises');
 var fastXmlParser = require('fast-xml-parser');
+var fs = require('fs/promises');
+var net = require('net');
 var os = require('os');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var path__namespace = /*#__PURE__*/_interopNamespace(path);
 var kill__default = /*#__PURE__*/_interopDefault(kill);
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
+var net__namespace = /*#__PURE__*/_interopNamespace(net);
+var os__namespace = /*#__PURE__*/_interopNamespace(os);
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -29,12 +52,6 @@ function err(error) {
 function assertUnreachable(x) {
   throw new Error(`Exhaustive check failed: ${JSON.stringify(x)}`);
 }
-function unwrap(result) {
-  if (result.ok) {
-    return result.value;
-  }
-  throw result.error;
-}
 function mapResult(result, fn) {
   if (result.ok) {
     return ok(fn(result.value));
@@ -124,6 +141,11 @@ function createPort(input) {
   }
   return ok(input);
 }
+function tag(input) {
+  const result = createDicomTagPath(input);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
 var AETitleSchema = zod.z.string().min(AE_TITLE_MIN_LENGTH).max(AE_TITLE_MAX_LENGTH).regex(AE_TITLE_PATTERN);
 var PortSchema = zod.z.number().int().min(PORT_MIN).max(PORT_MAX);
 var DicomTagSchema = zod.z.string().regex(DICOM_TAG_PATTERN);
@@ -201,7 +223,7 @@ function binaryName(name) {
 }
 function hasRequiredBinaries(dir) {
   for (const bin of REQUIRED_BINARIES) {
-    if (!fs.existsSync(path.join(dir, binaryName(bin)))) {
+    if (!fs$1.existsSync(path.join(dir, binaryName(bin)))) {
       return false;
     }
   }
@@ -30259,8 +30281,8 @@ var dictionary_default = {
 
 // src/dicom/dictionary.ts
 var dictionary = dictionary_default;
-function lookupTag(tag) {
-  const key = tag.includes(",") ? tag.replace(/[(),]/g, "") : tag;
+function lookupTag(tag2) {
+  const key = tag2.includes(",") ? tag2.replace(/[(),]/g, "") : tag2;
   return dictionary[key.toUpperCase()];
 }
 var nameIndex;
@@ -30427,13 +30449,13 @@ function advancePastMatch(remaining, matchLength) {
   if (after.length === 1) throw new Error("Tag path cannot end with a dot separator");
   return after.slice(1);
 }
-function tagPathToSegments(path) {
+function tagPathToSegments(path2) {
   const segments = [];
-  let remaining = path;
+  let remaining = path2;
   for (let i = 0; i < MAX_TRAVERSAL_DEPTH && remaining.length > 0; i++) {
     const match = SEGMENT_PATTERN.exec(remaining);
     if (match === null) {
-      throw new Error(`Invalid tag path segment at position ${path.length - remaining.length}: "${remaining}"`);
+      throw new Error(`Invalid tag path segment at position ${path2.length - remaining.length}: "${remaining}"`);
     }
     segments.push(matchToSegment(match));
     remaining = advancePastMatch(remaining, match[0].length);
@@ -30474,18 +30496,18 @@ function isValidDicomJsonModel(obj) {
 }
 var TAG_WITH_PARENS = /^\(([0-9A-Fa-f]{4}),([0-9A-Fa-f]{4})\)$/;
 var TAG_HEX_ONLY = /^[0-9A-Fa-f]{8}$/;
-function normalizeTag(tag) {
-  const parenMatch = TAG_WITH_PARENS.exec(tag);
+function normalizeTag(tag2) {
+  const parenMatch = TAG_WITH_PARENS.exec(tag2);
   if (parenMatch !== null) {
     const group = parenMatch[1];
     const element = parenMatch[2];
-    if (group === void 0 || element === void 0) return err(new Error(`Invalid tag: "${tag}"`));
+    if (group === void 0 || element === void 0) return err(new Error(`Invalid tag: "${tag2}"`));
     return ok(`${group}${element}`.toUpperCase());
   }
-  if (TAG_HEX_ONLY.test(tag)) {
-    return ok(tag.toUpperCase());
+  if (TAG_HEX_ONLY.test(tag2)) {
+    return ok(tag2.toUpperCase());
   }
-  return err(new Error(`Invalid tag format: "${tag}". Expected (XXXX,XXXX) or XXXXXXXX`));
+  return err(new Error(`Invalid tag format: "${tag2}". Expected (XXXX,XXXX) or XXXXXXXX`));
 }
 function resolveElement(data, tagKey) {
   return data[tagKey];
@@ -30666,11 +30688,11 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns Result containing the element or an error if not found
    */
-  getElement(tag) {
-    const norm = normalizeTag(tag);
+  getElement(tag2) {
+    const norm = normalizeTag(tag2);
     if (!norm.ok) return err(norm.error);
     const element = resolveElement(this.data, norm.value);
-    if (element === void 0) return err(new Error(`Tag ${tag} not found`));
+    if (element === void 0) return err(new Error(`Tag ${tag2} not found`));
     return ok(element);
   }
   /**
@@ -30679,11 +30701,11 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns Result containing the readonly Value array or an error
    */
-  getValue(tag) {
-    const elemResult = this.getElement(tag);
+  getValue(tag2) {
+    const elemResult = this.getElement(tag2);
     if (!elemResult.ok) return err(elemResult.error);
     const values = elemResult.value.Value;
-    if (values === void 0) return err(new Error(`Tag ${tag} has no Value`));
+    if (values === void 0) return err(new Error(`Tag ${tag2} has no Value`));
     return ok(values);
   }
   /**
@@ -30692,11 +30714,11 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns Result containing the first value or an error
    */
-  getFirstValue(tag) {
-    const valResult = this.getValue(tag);
+  getFirstValue(tag2) {
+    const valResult = this.getValue(tag2);
     if (!valResult.ok) return err(valResult.error);
     const first = valResult.value[0];
-    if (first === void 0) return err(new Error(`Tag ${tag} Value array is empty`));
+    if (first === void 0) return err(new Error(`Tag ${tag2} Value array is empty`));
     return ok(first);
   }
   /**
@@ -30709,8 +30731,8 @@ var DicomDataset = class _DicomDataset {
    * @param fallback - Value to return if tag is missing (default: `''`)
    * @returns The string value or the fallback
    */
-  getString(tag, fallback = "") {
-    const elemResult = this.getElement(tag);
+  getString(tag2, fallback = "") {
+    const elemResult = this.getElement(tag2);
     if (!elemResult.ok) return fallback;
     const str = extractString(elemResult.value);
     return str.length > 0 ? str : fallback;
@@ -30721,8 +30743,8 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns Result containing the number or an error
    */
-  getNumber(tag) {
-    const elemResult = this.getElement(tag);
+  getNumber(tag2) {
+    const elemResult = this.getElement(tag2);
     if (!elemResult.ok) return err(elemResult.error);
     return extractNumber(elemResult.value);
   }
@@ -30734,8 +30756,8 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns Result containing the readonly string array or an error
    */
-  getStrings(tag) {
-    const elemResult = this.getElement(tag);
+  getStrings(tag2) {
+    const elemResult = this.getElement(tag2);
     if (!elemResult.ok) return err(elemResult.error);
     return ok(extractStrings(elemResult.value));
   }
@@ -30745,8 +30767,8 @@ var DicomDataset = class _DicomDataset {
    * @param tag - A DicomTag `(0010,0010)` or hex string `00100010`
    * @returns `true` if the tag is present
    */
-  hasTag(tag) {
-    const norm = normalizeTag(tag);
+  hasTag(tag2) {
+    const norm = normalizeTag(tag2);
     if (!norm.ok) return false;
     return resolveElement(this.data, norm.value) !== void 0;
   }
@@ -30756,10 +30778,10 @@ var DicomDataset = class _DicomDataset {
    * @param path - A branded DicomTagPath, e.g. `(0040,A730)[0].(0040,A160)`
    * @returns Result containing the element at the path or an error
    */
-  getElementAtPath(path) {
+  getElementAtPath(path2) {
     let segments;
     try {
-      segments = tagPathToSegments(path);
+      segments = tagPathToSegments(path2);
     } catch (e) {
       return err(stderrLib.stderr(e));
     }
@@ -30776,10 +30798,10 @@ var DicomDataset = class _DicomDataset {
    * @param path - A branded DicomTagPath, e.g. `(0040,A730)[*].(0040,A160)`
    * @returns A readonly array of all matching values (may be empty)
    */
-  findValues(path) {
+  findValues(path2) {
     let segments;
     try {
-      segments = tagPathToSegments(path);
+      segments = tagPathToSegments(path2);
     } catch {
       return [];
     }
@@ -30862,6 +30884,18 @@ function buildMergedModifications(base, other, erasures) {
   }
   return merged;
 }
+function applyBatchEntries(initial, entries) {
+  const keys = Object.keys(entries);
+  let cs = initial;
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (key === void 0) continue;
+    const value = entries[key];
+    if (value === void 0) continue;
+    cs = cs.setTag(key, value);
+  }
+  return cs;
+}
 var ChangeSet = class _ChangeSet {
   constructor(mods, erasures) {
     __publicField(this, "mods");
@@ -30879,22 +30913,22 @@ var ChangeSet = class _ChangeSet {
    * Control characters (except LF/CR) are stripped from the value.
    * If the tag was previously erased, it is removed from the erasure set.
    *
-   * @param path - The DICOM tag path to set
+   * @param path - The DICOM tag path to set (e.g. `'(0010,0010)'`)
    * @param value - The new value for the tag
    * @returns A new ChangeSet with the modification applied
    * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
    */
-  setTag(path, value) {
+  setTag(path2, value) {
     const totalOps = this.mods.size + this.erased.size;
     if (totalOps >= MAX_CHANGESET_OPERATIONS) {
       throw new Error(`ChangeSet operation limit (${MAX_CHANGESET_OPERATIONS}) exceeded`);
     }
-    tagPathToSegments(path);
+    tagPathToSegments(path2);
     const sanitized = sanitizeValue(value);
     const newMods = new Map(this.mods);
-    newMods.set(path, sanitized);
+    newMods.set(path2, sanitized);
     const newErasures = new Set(this.erased);
-    newErasures.delete(path);
+    newErasures.delete(path2);
     return new _ChangeSet(newMods, newErasures);
   }
   /**
@@ -30902,20 +30936,20 @@ var ChangeSet = class _ChangeSet {
    *
    * If the tag was previously set, the modification is removed.
    *
-   * @param path - The DICOM tag path to erase
+   * @param path - The DICOM tag path to erase (e.g. `'(0010,0010)'`)
    * @returns A new ChangeSet with the erasure applied
    * @throws Error if operation count would exceed MAX_CHANGESET_OPERATIONS
    */
-  eraseTag(path) {
+  eraseTag(path2) {
     const totalOps = this.mods.size + this.erased.size;
     if (totalOps >= MAX_CHANGESET_OPERATIONS) {
       throw new Error(`ChangeSet operation limit (${MAX_CHANGESET_OPERATIONS}) exceeded`);
     }
-    tagPathToSegments(path);
+    tagPathToSegments(path2);
     const newMods = new Map(this.mods);
-    newMods.delete(path);
+    newMods.delete(path2);
     const newErasures = new Set(this.erased);
-    newErasures.add(path);
+    newErasures.add(path2);
     return new _ChangeSet(newMods, newErasures);
   }
   /**
@@ -30933,6 +30967,50 @@ var ChangeSet = class _ChangeSet {
     newErasures.add(ERASE_PRIVATE_SENTINEL);
     return new _ChangeSet(new Map(this.mods), newErasures);
   }
+  // -----------------------------------------------------------------------
+  // Convenience setters for common DICOM tags
+  // -----------------------------------------------------------------------
+  /** Sets Patient's Name (0010,0010). */
+  setPatientName(value) {
+    return this.setTag("(0010,0010)", value);
+  }
+  /** Sets Patient ID (0010,0020). */
+  setPatientID(value) {
+    return this.setTag("(0010,0020)", value);
+  }
+  /** Sets Study Date (0008,0020). */
+  setStudyDate(value) {
+    return this.setTag("(0008,0020)", value);
+  }
+  /** Sets Modality (0008,0060). */
+  setModality(value) {
+    return this.setTag("(0008,0060)", value);
+  }
+  /** Sets Accession Number (0008,0050). */
+  setAccessionNumber(value) {
+    return this.setTag("(0008,0050)", value);
+  }
+  /** Sets Study Description (0008,1030). */
+  setStudyDescription(value) {
+    return this.setTag("(0008,1030)", value);
+  }
+  /** Sets Series Description (0008,103E). */
+  setSeriesDescription(value) {
+    return this.setTag("(0008,103E)", value);
+  }
+  /** Sets Institution Name (0008,0080). */
+  setInstitutionName(value) {
+    return this.setTag("(0008,0080)", value);
+  }
+  /**
+   * Sets multiple tags at once, returning a new ChangeSet.
+   *
+   * @param entries - A record of tag path → value pairs
+   * @returns A new ChangeSet with all modifications applied
+   */
+  setBatch(entries) {
+    return applyBatchEntries(this, entries);
+  }
   /** All pending tag modifications as a readonly map of path → value. */
   get modifications() {
     return this.mods;
@@ -30975,8 +31053,8 @@ var ChangeSet = class _ChangeSet {
    */
   toModifications() {
     const result = [];
-    for (const [tag, value] of this.mods) {
-      result.push({ tag, value });
+    for (const [tag2, value] of this.mods) {
+      result.push({ tag: tag2, value });
     }
     return result;
   }
@@ -30990,9 +31068,9 @@ var ChangeSet = class _ChangeSet {
    */
   toErasureArgs() {
     const result = [];
-    for (const path of this.erased) {
-      if (path !== ERASE_PRIVATE_SENTINEL) {
-        result.push(path);
+    for (const path2 of this.erased) {
+      if (path2 !== ERASE_PRIVATE_SENTINEL) {
+        result.push(path2);
       }
     }
     return result;
@@ -31034,12 +31112,72 @@ function createValidationError(toolName, zodError) {
   for (let i = 0; i < zodError.issues.length; i++) {
     const issue = zodError.issues[i];
     if (issue === void 0) continue;
-    const path = issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
-    parts.push(`${path}: ${issue.message}`);
+    const path2 = issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
+    parts.push(`${path2}: ${issue.message}`);
   }
   const detail = parts.length > 0 ? parts.join("; ") : "unknown validation error";
   return new Error(`${toolName}: invalid options \u2014 ${detail}`);
 }
+
+// src/tools/dcm2xml.ts
+var Dcm2xmlCharset = {
+  /** Use UTF-8 encoding (default). */
+  UTF8: "utf8",
+  /** Use Latin-1 encoding. */
+  LATIN1: "latin1",
+  /** Use ASCII encoding. */
+  ASCII: "ascii"
+};
+var Dcm2xmlOptionsSchema = zod.z.object({
+  timeoutMs: zod.z.number().int().positive().optional(),
+  signal: zod.z.instanceof(AbortSignal).optional(),
+  namespace: zod.z.boolean().optional(),
+  charset: zod.z.enum(["utf8", "latin1", "ascii"]).optional(),
+  writeBinaryData: zod.z.boolean().optional(),
+  encodeBinaryBase64: zod.z.boolean().optional()
+}).strict().optional();
+function buildArgs(inputPath, options) {
+  const args = [];
+  if (options?.namespace === true) {
+    args.push("+Xn");
+  }
+  if (options?.charset === "latin1") {
+    args.push("+Cl");
+  } else if (options?.charset === "ascii") {
+    args.push("+Ca");
+  }
+  if (options?.writeBinaryData === true) {
+    args.push("+Wb");
+    if (options.encodeBinaryBase64 !== false) {
+      args.push("+Eb");
+    }
+  }
+  args.push(inputPath);
+  return args;
+}
+async function dcm2xml(inputPath, options) {
+  const validation = Dcm2xmlOptionsSchema.safeParse(options);
+  if (!validation.success) {
+    return err(createValidationError("dcm2xml", validation.error));
+  }
+  const binaryResult = resolveBinary("dcm2xml");
+  if (!binaryResult.ok) {
+    return err(binaryResult.error);
+  }
+  const args = buildArgs(inputPath, options);
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const result = await execCommand(binaryResult.value, args, {
+    timeoutMs,
+    signal: options?.signal
+  });
+  if (!result.ok) {
+    return err(result.error);
+  }
+  if (result.value.exitCode !== 0) {
+    return err(createToolError("dcm2xml", args, result.value.exitCode, result.value.stderr));
+  }
+  return ok({ xml: result.value.stdout });
+}
 var PN_REPS = ["Alphabetic", "Ideographic", "Phonetic"];
 var ARRAY_TAG_NAMES = /* @__PURE__ */ new Set(["DicomAttribute", "Value", "PersonName", "Item"]);
 var KNOWN_VR_CODES = /* @__PURE__ */ new Set([
@@ -31175,9 +31313,9 @@ function convertAttributes(obj) {
   for (const attr of attrs) {
     if (typeof attr !== "object" || attr === null) continue;
     const xmlAttr = attr;
-    const tag = xmlAttr["@_tag"];
-    if (tag === void 0) continue;
-    result[tag] = convertElement(xmlAttr);
+    const tag2 = xmlAttr["@_tag"];
+    if (tag2 === void 0) continue;
+    result[tag2] = convertElement(xmlAttr);
   }
   return result;
 }
@@ -31300,263 +31438,6 @@ async function dcm2json(inputPath, options) {
   }
   return tryDirectPath(inputPath, timeoutMs, signal);
 }
-var TAG_OR_PATH_PATTERN = /^\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\](\.\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\])?)*)?$/;
-var TagModificationSchema = zod.z.object({
-  tag: zod.z.string().regex(TAG_OR_PATH_PATTERN),
-  value: zod.z.string()
-});
-var DcmodifyOptionsSchema = zod.z.object({
-  timeoutMs: zod.z.number().int().positive().optional(),
-  signal: zod.z.instanceof(AbortSignal).optional(),
-  modifications: zod.z.array(TagModificationSchema).optional().default([]),
-  erasures: zod.z.array(zod.z.string()).optional(),
-  erasePrivateTags: zod.z.boolean().optional(),
-  noBackup: zod.z.boolean().optional(),
-  insertIfMissing: zod.z.boolean().optional()
-}).strict().refine((data) => data.modifications.length > 0 || data.erasures !== void 0 && data.erasures.length > 0 || data.erasePrivateTags === true, {
-  message: "At least one of modifications, erasures, or erasePrivateTags is required"
-});
-function buildArgs(inputPath, options) {
-  const args = [];
-  if (options.noBackup !== false) {
-    args.push("-nb");
-  }
-  const flag = options.insertIfMissing === true ? "-i" : "-m";
-  const modifications = options.modifications ?? [];
-  for (const mod of modifications) {
-    args.push(flag, `${mod.tag}=${mod.value}`);
-  }
-  if (options.erasures !== void 0) {
-    for (const erasure of options.erasures) {
-      args.push("-e", erasure);
-    }
-  }
-  if (options.erasePrivateTags === true) {
-    args.push("-ep");
-  }
-  args.push(inputPath);
-  return args;
-}
-async function dcmodify(inputPath, options) {
-  const validation = DcmodifyOptionsSchema.safeParse(options);
-  if (!validation.success) {
-    return err(new Error(`dcmodify: invalid options: ${validation.error.message}`));
-  }
-  const binaryResult = resolveBinary("dcmodify");
-  if (!binaryResult.ok) {
-    return err(binaryResult.error);
-  }
-  const args = buildArgs(inputPath, options);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const result = await spawnCommand(binaryResult.value, args, {
-    timeoutMs,
-    signal: options.signal
-  });
-  if (!result.ok) {
-    return err(result.error);
-  }
-  if (result.value.exitCode !== 0) {
-    return err(createToolError("dcmodify", args, result.value.exitCode, result.value.stderr));
-  }
-  return ok({ filePath: inputPath });
-}
-
-// src/dicom/DicomFile.ts
-async function applyModifications(filePath, changeset, options) {
-  const modifications = changeset.toModifications();
-  const erasures = changeset.toErasureArgs();
-  const result = await dcmodify(filePath, {
-    modifications: modifications.length > 0 ? modifications : void 0,
-    erasures: erasures.length > 0 ? erasures : void 0,
-    erasePrivateTags: changeset.erasePrivate || void 0,
-    insertIfMissing: true,
-    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    signal: options.signal
-  });
-  if (!result.ok) return err(result.error);
-  return ok(void 0);
-}
-async function copyFileSafe(source, dest) {
-  return stderrLib.tryCatch(
-    () => promises.copyFile(source, dest),
-    (e) => new Error(`Failed to copy file: ${e.message}`)
-  );
-}
-async function statFileSize(path) {
-  return stderrLib.tryCatch(
-    async () => (await promises.stat(path)).size,
-    (e) => new Error(`Failed to stat file: ${e.message}`)
-  );
-}
-async function unlinkFile(path) {
-  return stderrLib.tryCatch(
-    () => promises.unlink(path),
-    (e) => new Error(`Failed to delete file: ${e.message}`)
-  );
-}
-var DicomFile = class _DicomFile {
-  constructor(dataset, filePath, changes) {
-    /** The immutable DICOM dataset read from the file. */
-    __publicField(this, "dataset");
-    /** The branded file path. */
-    __publicField(this, "filePath");
-    /** The accumulated pending changes. */
-    __publicField(this, "changes");
-    this.dataset = dataset;
-    this.filePath = filePath;
-    this.changes = changes;
-  }
-  /**
-   * Opens a DICOM file and reads its dataset.
-   *
-   * @param path - Filesystem path to the DICOM file
-   * @param options - Timeout and abort options
-   * @returns A Result containing the DicomFile or an error
-   */
-  static async open(path, options) {
-    const filePathResult = createDicomFilePath(path);
-    if (!filePathResult.ok) return err(filePathResult.error);
-    const jsonResult = await dcm2json(path, {
-      timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      signal: options?.signal
-    });
-    if (!jsonResult.ok) return err(jsonResult.error);
-    const datasetResult = DicomDataset.fromJson(jsonResult.value.data);
-    if (!datasetResult.ok) return err(datasetResult.error);
-    return ok(new _DicomFile(datasetResult.value, filePathResult.value, ChangeSet.empty()));
-  }
-  /**
-   * Returns a new DicomFile with the given changes merged into the pending changes.
-   *
-   * @param changes - A ChangeSet to merge with existing pending changes
-   * @returns A new DicomFile with accumulated changes
-   */
-  withChanges(changes) {
-    return new _DicomFile(this.dataset, this.filePath, this.changes.merge(changes));
-  }
-  /**
-   * Returns a new DicomFile with a different file path.
-   *
-   * Preserves the dataset and pending changes.
-   *
-   * @param newPath - The new branded file path
-   * @returns A new DicomFile pointing to the new path
-   */
-  withFilePath(newPath) {
-    return new _DicomFile(this.dataset, newPath, this.changes);
-  }
-  /**
-   * Applies pending changes to the file in-place using dcmodify.
-   *
-   * If there are no pending changes, this is a no-op that returns success.
-   * After applying, the dataset is NOT refreshed — call {@link DicomFile.open}
-   * again if you need fresh data.
-   *
-   * @param options - Timeout and abort options
-   * @returns A Result indicating success or failure
-   */
-  async applyChanges(options) {
-    if (this.changes.isEmpty) return ok(void 0);
-    return applyModifications(this.filePath, this.changes, options ?? {});
-  }
-  /**
-   * Copies the file to a new path and applies pending changes to the copy.
-   *
-   * If there are no pending changes, only the copy is performed.
-   * On dcmodify failure, the copy is cleaned up.
-   *
-   * @param outputPath - Destination filesystem path
-   * @param options - Timeout and abort options
-   * @returns A Result containing the branded output path or an error
-   */
-  async writeAs(outputPath, options) {
-    const outPathResult = createDicomFilePath(outputPath);
-    if (!outPathResult.ok) return err(outPathResult.error);
-    const copyResult = await copyFileSafe(this.filePath, outputPath);
-    if (!copyResult.ok) return err(copyResult.error);
-    if (this.changes.isEmpty) return ok(outPathResult.value);
-    const applyResult = await applyModifications(outPathResult.value, this.changes, options ?? {});
-    if (!applyResult.ok) {
-      await unlinkFile(outputPath);
-      return err(applyResult.error);
-    }
-    return ok(outPathResult.value);
-  }
-  /**
-   * Gets the file size in bytes.
-   *
-   * @returns A Result containing the size or an error
-   */
-  async fileSize() {
-    return statFileSize(this.filePath);
-  }
-  /**
-   * Deletes the file from the filesystem.
-   *
-   * @returns A Result indicating success or failure
-   */
-  async unlink() {
-    return unlinkFile(this.filePath);
-  }
-};
-var Dcm2xmlCharset = {
-  /** Use UTF-8 encoding (default). */
-  UTF8: "utf8",
-  /** Use Latin-1 encoding. */
-  LATIN1: "latin1",
-  /** Use ASCII encoding. */
-  ASCII: "ascii"
-};
-var Dcm2xmlOptionsSchema = zod.z.object({
-  timeoutMs: zod.z.number().int().positive().optional(),
-  signal: zod.z.instanceof(AbortSignal).optional(),
-  namespace: zod.z.boolean().optional(),
-  charset: zod.z.enum(["utf8", "latin1", "ascii"]).optional(),
-  writeBinaryData: zod.z.boolean().optional(),
-  encodeBinaryBase64: zod.z.boolean().optional()
-}).strict().optional();
-function buildArgs2(inputPath, options) {
-  const args = [];
-  if (options?.namespace === true) {
-    args.push("+Xn");
-  }
-  if (options?.charset === "latin1") {
-    args.push("+Cl");
-  } else if (options?.charset === "ascii") {
-    args.push("+Ca");
-  }
-  if (options?.writeBinaryData === true) {
-    args.push("+Wb");
-    if (options.encodeBinaryBase64 !== false) {
-      args.push("+Eb");
-    }
-  }
-  args.push(inputPath);
-  return args;
-}
-async function dcm2xml(inputPath, options) {
-  const validation = Dcm2xmlOptionsSchema.safeParse(options);
-  if (!validation.success) {
-    return err(new Error(`dcm2xml: invalid options: ${validation.error.message}`));
-  }
-  const binaryResult = resolveBinary("dcm2xml");
-  if (!binaryResult.ok) {
-    return err(binaryResult.error);
-  }
-  const args = buildArgs2(inputPath, options);
-  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const result = await execCommand(binaryResult.value, args, {
-    timeoutMs,
-    signal: options?.signal
-  });
-  if (!result.ok) {
-    return err(result.error);
-  }
-  if (result.value.exitCode !== 0) {
-    return err(createToolError("dcm2xml", args, result.value.exitCode, result.value.stderr));
-  }
-  return ok({ xml: result.value.stdout });
-}
 var DcmdumpFormat = {
   /** Print standard DCMTK format. */
   STANDARD: "standard",
@@ -31571,7 +31452,7 @@ var DcmdumpOptionsSchema = zod.z.object({
   searchTag: zod.z.string().regex(/^\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)$/).optional(),
   printValues: zod.z.boolean().optional()
 }).strict().optional();
-function buildArgs3(inputPath, options) {
+function buildArgs2(inputPath, options) {
   const args = [];
   if (options?.format === "short") {
     args.push("+L");
@@ -31580,8 +31461,8 @@ function buildArgs3(inputPath, options) {
     args.push("+P", "all");
   }
   if (options?.searchTag !== void 0) {
-    const tag = options.searchTag.replace(/[()]/g, "");
-    args.push("+P", tag);
+    const tag2 = options.searchTag.replace(/[()]/g, "");
+    args.push("+P", tag2);
   }
   if (options?.printValues === true) {
     args.push("+Vr");
@@ -31592,13 +31473,13 @@ function buildArgs3(inputPath, options) {
 async function dcmdump(inputPath, options) {
   const validation = DcmdumpOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdump: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdump", validation.error));
   }
   const binaryResult = resolveBinary("dcmdump");
   if (!binaryResult.ok) {
     return err(binaryResult.error);
   }
-  const args = buildArgs3(inputPath, options);
+  const args = buildArgs2(inputPath, options);
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const result = await execCommand(binaryResult.value, args, {
     timeoutMs,
@@ -31637,7 +31518,7 @@ var DcmconvOptionsSchema = zod.z.object({
 async function dcmconv(inputPath, outputPath, options) {
   const validation = DcmconvOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmconv: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmconv", validation.error));
   }
   const binaryResult = resolveBinary("dcmconv");
   if (!binaryResult.ok) {
@@ -31657,6 +31538,70 @@ async function dcmconv(inputPath, outputPath, options) {
   }
   return ok({ outputPath });
 }
+var TAG_OR_PATH_PATTERN = /^\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\](\.\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\])?)*)?$/;
+var TagModificationSchema = zod.z.object({
+  tag: zod.z.string().regex(TAG_OR_PATH_PATTERN),
+  value: zod.z.string()
+});
+var DcmodifyOptionsSchema = zod.z.object({
+  timeoutMs: zod.z.number().int().positive().optional(),
+  signal: zod.z.instanceof(AbortSignal).optional(),
+  modifications: zod.z.array(TagModificationSchema).optional().default([]),
+  erasures: zod.z.array(zod.z.string()).optional(),
+  erasePrivateTags: zod.z.boolean().optional(),
+  noBackup: zod.z.boolean().optional(),
+  insertIfMissing: zod.z.boolean().optional(),
+  ignoreMissingTags: zod.z.boolean().optional()
+}).strict().refine((data) => data.modifications.length > 0 || data.erasures !== void 0 && data.erasures.length > 0 || data.erasePrivateTags === true, {
+  message: "At least one of modifications, erasures, or erasePrivateTags is required"
+});
+function buildArgs3(inputPath, options) {
+  const args = [];
+  if (options.noBackup !== false) {
+    args.push("-nb");
+  }
+  if (options.ignoreMissingTags === true) {
+    args.push("-imt");
+  }
+  const flag = options.insertIfMissing === true ? "-i" : "-m";
+  const modifications = options.modifications ?? [];
+  for (const mod of modifications) {
+    args.push(flag, `${mod.tag}=${mod.value}`);
+  }
+  if (options.erasures !== void 0) {
+    for (const erasure of options.erasures) {
+      args.push("-e", erasure);
+    }
+  }
+  if (options.erasePrivateTags === true) {
+    args.push("-ep");
+  }
+  args.push(inputPath);
+  return args;
+}
+async function dcmodify(inputPath, options) {
+  const validation = DcmodifyOptionsSchema.safeParse(options);
+  if (!validation.success) {
+    return err(createValidationError("dcmodify", validation.error));
+  }
+  const binaryResult = resolveBinary("dcmodify");
+  if (!binaryResult.ok) {
+    return err(binaryResult.error);
+  }
+  const args = buildArgs3(inputPath, options);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const result = await spawnCommand(binaryResult.value, args, {
+    timeoutMs,
+    signal: options.signal
+  });
+  if (!result.ok) {
+    return err(result.error);
+  }
+  if (result.value.exitCode !== 0) {
+    return err(createToolError("dcmodify", args, result.value.exitCode, result.value.stderr));
+  }
+  return ok({ filePath: inputPath });
+}
 var DcmftestOptionsSchema = zod.z.object({
   timeoutMs: zod.z.number().int().positive().optional(),
   signal: zod.z.instanceof(AbortSignal).optional()
@@ -31664,7 +31609,7 @@ var DcmftestOptionsSchema = zod.z.object({
 async function dcmftest(inputPath, options) {
   const validation = DcmftestOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmftest: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmftest", validation.error));
   }
   const binaryResult = resolveBinary("dcmftest");
   if (!binaryResult.ok) {
@@ -31719,7 +31664,7 @@ function buildArgs4(options) {
 async function dcmgpdir(options) {
   const validation = DcmgpdirOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmgpdir: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmgpdir", validation.error));
   }
   const binaryResult = resolveBinary("dcmgpdir");
   if (!binaryResult.ok) {
@@ -31778,7 +31723,7 @@ function buildArgs5(options) {
 async function dcmmkdir(options) {
   const validation = DcmmkdirOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmmkdir: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmmkdir", validation.error));
   }
   const binaryResult = resolveBinary("dcmmkdir");
   if (!binaryResult.ok) {
@@ -31826,7 +31771,7 @@ function buildArgs6(options) {
 async function dcmqridx(options) {
   const validation = DcmqridxOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmqridx: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmqridx", validation.error));
   }
   const binaryResult = resolveBinary("dcmqridx");
   if (!binaryResult.ok) {
@@ -31869,7 +31814,7 @@ function buildArgs7(inputPath, outputPath, options) {
 async function xml2dcm(inputPath, outputPath, options) {
   const validation = Xml2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`xml2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("xml2dcm", validation.error));
   }
   const binaryResult = resolveBinary("xml2dcm");
   if (!binaryResult.ok) {
@@ -31896,7 +31841,7 @@ var Json2dcmOptionsSchema = zod.z.object({
 async function json2dcm(inputPath, outputPath, options) {
   const validation = Json2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`json2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("json2dcm", validation.error));
   }
   const binaryResult = resolveBinary("json2dcm");
   if (!binaryResult.ok) {
@@ -31936,7 +31881,7 @@ function buildArgs8(inputPath, outputPath, options) {
 async function dump2dcm(inputPath, outputPath, options) {
   const validation = Dump2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dump2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dump2dcm", validation.error));
   }
   const binaryResult = resolveBinary("dump2dcm");
   if (!binaryResult.ok) {
@@ -31986,7 +31931,7 @@ function buildArgs9(inputPath, outputPath, options) {
 async function img2dcm(inputPath, outputPath, options) {
   const validation = Img2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`img2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("img2dcm", validation.error));
   }
   const binaryResult = resolveBinary("img2dcm");
   if (!binaryResult.ok) {
@@ -32013,7 +31958,7 @@ var Pdf2dcmOptionsSchema = zod.z.object({
 async function pdf2dcm(inputPath, outputPath, options) {
   const validation = Pdf2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`pdf2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("pdf2dcm", validation.error));
   }
   const binaryResult = resolveBinary("pdf2dcm");
   if (!binaryResult.ok) {
@@ -32040,7 +31985,7 @@ var Dcm2pdfOptionsSchema = zod.z.object({
 async function dcm2pdf(inputPath, outputPath, options) {
   const validation = Dcm2pdfOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcm2pdf: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcm2pdf", validation.error));
   }
   const binaryResult = resolveBinary("dcm2pdf");
   if (!binaryResult.ok) {
@@ -32067,7 +32012,7 @@ var Cda2dcmOptionsSchema = zod.z.object({
 async function cda2dcm(inputPath, outputPath, options) {
   const validation = Cda2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`cda2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("cda2dcm", validation.error));
   }
   const binaryResult = resolveBinary("cda2dcm");
   if (!binaryResult.ok) {
@@ -32094,7 +32039,7 @@ var Dcm2cdaOptionsSchema = zod.z.object({
 async function dcm2cda(inputPath, outputPath, options) {
   const validation = Dcm2cdaOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcm2cda: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcm2cda", validation.error));
   }
   const binaryResult = resolveBinary("dcm2cda");
   if (!binaryResult.ok) {
@@ -32121,7 +32066,7 @@ var Stl2dcmOptionsSchema = zod.z.object({
 async function stl2dcm(inputPath, outputPath, options) {
   const validation = Stl2dcmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`stl2dcm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("stl2dcm", validation.error));
   }
   const binaryResult = resolveBinary("stl2dcm");
   if (!binaryResult.ok) {
@@ -32157,7 +32102,7 @@ function buildArgs10(inputPath, outputPath, options) {
 async function dcmcrle(inputPath, outputPath, options) {
   const validation = DcmcrleOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmcrle: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmcrle", validation.error));
   }
   const binaryResult = resolveBinary("dcmcrle");
   if (!binaryResult.ok) {
@@ -32193,7 +32138,7 @@ function buildArgs11(inputPath, outputPath, options) {
 async function dcmdrle(inputPath, outputPath, options) {
   const validation = DcmdrleOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdrle: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdrle", validation.error));
   }
   const binaryResult = resolveBinary("dcmdrle");
   if (!binaryResult.ok) {
@@ -32229,7 +32174,7 @@ function buildArgs12(inputPath, outputPath, options) {
 async function dcmencap(inputPath, outputPath, options) {
   const validation = DcmencapOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmencap: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmencap", validation.error));
   }
   const binaryResult = resolveBinary("dcmencap");
   if (!binaryResult.ok) {
@@ -32256,7 +32201,7 @@ var DcmdecapOptionsSchema = zod.z.object({
 async function dcmdecap(inputPath, outputPath, options) {
   const validation = DcmdecapOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdecap: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdecap", validation.error));
   }
   const binaryResult = resolveBinary("dcmdecap");
   if (!binaryResult.ok) {
@@ -32296,7 +32241,7 @@ function buildArgs13(inputPath, outputPath, options) {
 async function dcmcjpeg(inputPath, outputPath, options) {
   const validation = DcmcjpegOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmcjpeg: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmcjpeg", validation.error));
   }
   const binaryResult = resolveBinary("dcmcjpeg");
   if (!binaryResult.ok) {
@@ -32345,7 +32290,7 @@ function buildArgs14(inputPath, outputPath, options) {
 async function dcmdjpeg(inputPath, outputPath, options) {
   const validation = DcmdjpegOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdjpeg: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdjpeg", validation.error));
   }
   const binaryResult = resolveBinary("dcmdjpeg");
   if (!binaryResult.ok) {
@@ -32387,7 +32332,7 @@ function buildArgs15(inputPath, outputPath, options) {
 async function dcmcjpls(inputPath, outputPath, options) {
   const validation = DcmcjplsOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmcjpls: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmcjpls", validation.error));
   }
   const binaryResult = resolveBinary("dcmcjpls");
   if (!binaryResult.ok) {
@@ -32436,7 +32381,7 @@ function buildArgs16(inputPath, outputPath, options) {
 async function dcmdjpls(inputPath, outputPath, options) {
   const validation = DcmdjplsOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdjpls: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdjpls", validation.error));
   }
   const binaryResult = resolveBinary("dcmdjpls");
   if (!binaryResult.ok) {
@@ -32495,7 +32440,7 @@ function buildArgs17(inputPath, outputPath, options) {
 async function dcmj2pnm(inputPath, outputPath, options) {
   const validation = Dcmj2pnmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmj2pnm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmj2pnm", validation.error));
   }
   const binaryResult = resolveBinary("dcmj2pnm");
   if (!binaryResult.ok) {
@@ -32551,7 +32496,7 @@ function buildArgs18(inputPath, outputPath, options) {
 async function dcm2pnm(inputPath, outputPath, options) {
   const validation = Dcm2pnmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcm2pnm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcm2pnm", validation.error));
   }
   const binaryResult = resolveBinary("dcm2pnm");
   if (!binaryResult.ok) {
@@ -32599,7 +32544,7 @@ function buildArgs19(inputPath, outputPath, options) {
 async function dcmscale(inputPath, outputPath, options) {
   const validation = DcmscaleOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmscale: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmscale", validation.error));
   }
   const binaryResult = resolveBinary("dcmscale");
   if (!binaryResult.ok) {
@@ -32639,7 +32584,7 @@ function buildArgs20(inputPath, outputPath, options) {
 async function dcmquant(inputPath, outputPath, options) {
   const validation = DcmquantOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmquant: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmquant", validation.error));
   }
   const binaryResult = resolveBinary("dcmquant");
   if (!binaryResult.ok) {
@@ -32686,7 +32631,7 @@ function buildArgs21(options) {
 async function dcmdspfn(options) {
   const validation = DcmdspfnOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmdspfn: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmdspfn", validation.error));
   }
   const binaryResult = resolveBinary("dcmdspfn");
   if (!binaryResult.ok) {
@@ -32713,7 +32658,7 @@ var Dcod2lumOptionsSchema = zod.z.object({
 async function dcod2lum(inputPath, outputPath, options) {
   const validation = Dcod2lumOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcod2lum: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcod2lum", validation.error));
   }
   const binaryResult = resolveBinary("dcod2lum");
   if (!binaryResult.ok) {
@@ -32749,7 +32694,7 @@ function buildArgs22(inputPath, outputPath, options) {
 async function dconvlum(inputPath, outputPath, options) {
   const validation = DconvlumOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dconvlum: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dconvlum", validation.error));
   }
   const binaryResult = resolveBinary("dconvlum");
   if (!binaryResult.ok) {
@@ -32839,7 +32784,7 @@ function buildArgs24(options) {
 async function dcmsend(options) {
   const validation = DcmsendOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmsend: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmsend", validation.error));
   }
   const binaryResult = resolveBinary("dcmsend");
   if (!binaryResult.ok) {
@@ -32859,6 +32804,32 @@ async function dcmsend(options) {
   }
   return ok({ success: true, stderr: result.value.stderr });
 }
+var ProposedTransferSyntax = {
+  UNCOMPRESSED: "uncompressed",
+  LITTLE_ENDIAN: "littleEndian",
+  BIG_ENDIAN: "bigEndian",
+  IMPLICIT_VR: "implicitVR",
+  JPEG_LOSSLESS: "jpegLossless",
+  JPEG_8BIT: "jpeg8Bit",
+  JPEG_12BIT: "jpeg12Bit",
+  J2K_LOSSLESS: "j2kLossless",
+  J2K_LOSSY: "j2kLossy",
+  JLS_LOSSLESS: "jlsLossless",
+  JLS_LOSSY: "jlsLossy"
+};
+var PROPOSED_TS_FLAG_MAP = {
+  [ProposedTransferSyntax.UNCOMPRESSED]: "-x=",
+  [ProposedTransferSyntax.LITTLE_ENDIAN]: "-xe",
+  [ProposedTransferSyntax.BIG_ENDIAN]: "-xb",
+  [ProposedTransferSyntax.IMPLICIT_VR]: "-xi",
+  [ProposedTransferSyntax.JPEG_LOSSLESS]: "-xs",
+  [ProposedTransferSyntax.JPEG_8BIT]: "-xy",
+  [ProposedTransferSyntax.JPEG_12BIT]: "-xx",
+  [ProposedTransferSyntax.J2K_LOSSLESS]: "-xv",
+  [ProposedTransferSyntax.J2K_LOSSY]: "-xw",
+  [ProposedTransferSyntax.JLS_LOSSLESS]: "-xt",
+  [ProposedTransferSyntax.JLS_LOSSY]: "-xu"
+};
 var StorescuOptionsSchema = zod.z.object({
   timeoutMs: zod.z.number().int().positive().optional(),
   signal: zod.z.instanceof(AbortSignal).optional(),
@@ -32868,7 +32839,20 @@ var StorescuOptionsSchema = zod.z.object({
   callingAETitle: zod.z.string().min(1).max(16).refine(isValidAETitle, { message: "AE Title contains invalid characters" }).optional(),
   calledAETitle: zod.z.string().min(1).max(16).refine(isValidAETitle, { message: "AE Title contains invalid characters" }).optional(),
   scanDirectories: zod.z.boolean().optional(),
-  recurse: zod.z.boolean().optional()
+  recurse: zod.z.boolean().optional(),
+  proposedTransferSyntax: zod.z.enum([
+    "uncompressed",
+    "littleEndian",
+    "bigEndian",
+    "implicitVR",
+    "jpegLossless",
+    "jpeg8Bit",
+    "jpeg12Bit",
+    "j2kLossless",
+    "j2kLossy",
+    "jlsLossless",
+    "jlsLossy"
+  ]).optional()
 }).strict();
 function buildArgs25(options) {
   const args = [];
@@ -32884,6 +32868,9 @@ function buildArgs25(options) {
   if (options.recurse === true) {
     args.push("+r");
   }
+  if (options.proposedTransferSyntax !== void 0) {
+    args.push(PROPOSED_TS_FLAG_MAP[options.proposedTransferSyntax]);
+  }
   args.push(options.host, String(options.port));
   args.push(...options.files);
   return args;
@@ -32891,7 +32878,7 @@ function buildArgs25(options) {
 async function storescu(options) {
   const validation = StorescuOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`storescu: invalid options: ${validation.error.message}`));
+    return err(createValidationError("storescu", validation.error));
   }
   const binaryResult = resolveBinary("storescu");
   if (!binaryResult.ok) {
@@ -33031,7 +33018,7 @@ function buildArgs27(options) {
 async function movescu(options) {
   const validation = MovescuOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`movescu: invalid options: ${validation.error.message}`));
+    return err(createValidationError("movescu", validation.error));
   }
   const binaryResult = resolveBinary("movescu");
   if (!binaryResult.ok) {
@@ -33095,7 +33082,7 @@ function buildArgs28(options) {
 async function getscu(options) {
   const validation = GetscuOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`getscu: invalid options: ${validation.error.message}`));
+    return err(createValidationError("getscu", validation.error));
   }
   const binaryResult = resolveBinary("getscu");
   if (!binaryResult.ok) {
@@ -33137,7 +33124,7 @@ function buildArgs29(options) {
 async function termscu(options) {
   const validation = TermscuOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`termscu: invalid options: ${validation.error.message}`));
+    return err(createValidationError("termscu", validation.error));
   }
   const binaryResult = resolveBinary("termscu");
   if (!binaryResult.ok) {
@@ -33181,7 +33168,7 @@ function buildArgs30(inputPath, options) {
 async function dsrdump(inputPath, options) {
   const validation = DsrdumpOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dsrdump: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dsrdump", validation.error));
   }
   const binaryResult = resolveBinary("dsrdump");
   if (!binaryResult.ok) {
@@ -33221,7 +33208,7 @@ function buildArgs31(inputPath, options) {
 async function dsr2xml(inputPath, options) {
   const validation = Dsr2xmlOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dsr2xml: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dsr2xml", validation.error));
   }
   const binaryResult = resolveBinary("dsr2xml");
   if (!binaryResult.ok) {
@@ -33261,7 +33248,7 @@ function buildArgs32(inputPath, outputPath, options) {
 async function xml2dsr(inputPath, outputPath, options) {
   const validation = Xml2dsrOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`xml2dsr: invalid options: ${validation.error.message}`));
+    return err(createValidationError("xml2dsr", validation.error));
   }
   const binaryResult = resolveBinary("xml2dsr");
   if (!binaryResult.ok) {
@@ -33297,7 +33284,7 @@ function buildArgs33(inputPath, options) {
 async function drtdump(inputPath, options) {
   const validation = DrtdumpOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`drtdump: invalid options: ${validation.error.message}`));
+    return err(createValidationError("drtdump", validation.error));
   }
   const binaryResult = resolveBinary("drtdump");
   if (!binaryResult.ok) {
@@ -33324,7 +33311,7 @@ var DcmpsmkOptionsSchema = zod.z.object({
 async function dcmpsmk(inputPath, outputPath, options) {
   const validation = DcmpsmkOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmpsmk: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmpsmk", validation.error));
   }
   const binaryResult = resolveBinary("dcmpsmk");
   if (!binaryResult.ok) {
@@ -33351,7 +33338,7 @@ var DcmpschkOptionsSchema = zod.z.object({
 async function dcmpschk(inputPath, options) {
   const validation = DcmpschkOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmpschk: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmpschk", validation.error));
   }
   const binaryResult = resolveBinary("dcmpschk");
   if (!binaryResult.ok) {
@@ -33397,7 +33384,7 @@ function buildArgs34(options) {
 async function dcmprscu(options) {
   const validation = DcmprscuOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmprscu: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmprscu", validation.error));
   }
   const binaryResult = resolveBinary("dcmprscu");
   if (!binaryResult.ok) {
@@ -33433,7 +33420,7 @@ function buildArgs35(inputPath, options) {
 async function dcmpsprt(inputPath, options) {
   const validation = DcmpsprtOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmpsprt: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmpsprt", validation.error));
   }
   const binaryResult = resolveBinary("dcmpsprt");
   if (!binaryResult.ok) {
@@ -33473,7 +33460,7 @@ function buildArgs36(inputPath, outputPath, options) {
 async function dcmp2pgm(inputPath, outputPath, options) {
   const validation = Dcmp2pgmOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmp2pgm: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmp2pgm", validation.error));
   }
   const binaryResult = resolveBinary("dcmp2pgm");
   if (!binaryResult.ok) {
@@ -33500,7 +33487,7 @@ var DcmmkcrvOptionsSchema = zod.z.object({
 async function dcmmkcrv(inputPath, outputPath, options) {
   const validation = DcmmkcrvOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmmkcrv: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmmkcrv", validation.error));
   }
   const binaryResult = resolveBinary("dcmmkcrv");
   if (!binaryResult.ok) {
@@ -33561,7 +33548,7 @@ function buildArgs37(outputPath, options) {
 async function dcmmklut(outputPath, options) {
   const validation = DcmmklutOptionsSchema.safeParse(options);
   if (!validation.success) {
-    return err(new Error(`dcmmklut: invalid options: ${validation.error.message}`));
+    return err(createValidationError("dcmmklut", validation.error));
   }
   const binaryResult = resolveBinary("dcmmklut");
   if (!binaryResult.ok) {
@@ -33581,6 +33568,363 @@ async function dcmmklut(outputPath, options) {
   }
   return ok({ outputPath });
 }
+async function applyModifications(filePath, changeset, options) {
+  const modifications = changeset.toModifications();
+  const erasures = changeset.toErasureArgs();
+  const hasErasures = erasures.length > 0 || changeset.erasePrivate;
+  const result = await dcmodify(filePath, {
+    modifications: modifications.length > 0 ? modifications : void 0,
+    erasures: erasures.length > 0 ? erasures : void 0,
+    erasePrivateTags: changeset.erasePrivate || void 0,
+    insertIfMissing: true,
+    ignoreMissingTags: hasErasures || void 0,
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    signal: options.signal
+  });
+  if (!result.ok) return err(result.error);
+  return ok(void 0);
+}
+async function copyFileSafe(source, dest) {
+  return stderrLib.tryCatch(
+    () => fs.copyFile(source, dest),
+    (e) => new Error(`Failed to copy file: ${e.message}`)
+  );
+}
+async function statFileSize(path2) {
+  return stderrLib.tryCatch(
+    async () => (await fs.stat(path2)).size,
+    (e) => new Error(`Failed to stat file: ${e.message}`)
+  );
+}
+async function unlinkFile(path2) {
+  return stderrLib.tryCatch(
+    () => fs.unlink(path2),
+    (e) => new Error(`Failed to delete file: ${e.message}`)
+  );
+}
+
+// src/dicom/DicomInstance.ts
+var DicomInstance = class _DicomInstance {
+  constructor(dataset, changes, filePath, metadata) {
+    __publicField(this, "dicomDataset");
+    __publicField(this, "changeSet");
+    __publicField(this, "filepath");
+    __publicField(this, "meta");
+    this.dicomDataset = dataset;
+    this.changeSet = changes;
+    this.filepath = filePath;
+    this.meta = metadata;
+  }
+  // -----------------------------------------------------------------------
+  // Factories
+  // -----------------------------------------------------------------------
+  /**
+   * Opens a DICOM file and creates a DicomInstance.
+   *
+   * @param path - Filesystem path to the DICOM file
+   * @param options - Timeout and abort options
+   * @returns A Result containing the DicomInstance or an error
+   */
+  static async open(path2, options) {
+    const filePathResult = createDicomFilePath(path2);
+    if (!filePathResult.ok) return err(filePathResult.error);
+    const jsonResult = await dcm2json(path2, {
+      timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      signal: options?.signal
+    });
+    if (!jsonResult.ok) return err(jsonResult.error);
+    const datasetResult = DicomDataset.fromJson(jsonResult.value.data);
+    if (!datasetResult.ok) return err(datasetResult.error);
+    return ok(new _DicomInstance(datasetResult.value, ChangeSet.empty(), filePathResult.value, /* @__PURE__ */ new Map()));
+  }
+  /**
+   * Creates a DicomInstance from an existing DicomDataset.
+   *
+   * @param dataset - The DicomDataset to wrap
+   * @param filePath - Optional file path (e.g. if the dataset came from a file)
+   * @returns A Result containing the DicomInstance
+   */
+  static fromDataset(dataset, filePath) {
+    let fp;
+    if (filePath !== void 0) {
+      const fpResult = createDicomFilePath(filePath);
+      if (!fpResult.ok) return err(fpResult.error);
+      fp = fpResult.value;
+    }
+    return ok(new _DicomInstance(dataset, ChangeSet.empty(), fp, /* @__PURE__ */ new Map()));
+  }
+  // -----------------------------------------------------------------------
+  // Read accessors (delegate to DicomDataset)
+  // -----------------------------------------------------------------------
+  /** The underlying immutable DICOM dataset. */
+  get dataset() {
+    return this.dicomDataset;
+  }
+  /** The pending change set. */
+  get changes() {
+    return this.changeSet;
+  }
+  /** Whether there are unsaved changes. */
+  get hasUnsavedChanges() {
+    return !this.changeSet.isEmpty;
+  }
+  /** The file path, or undefined if this instance has no associated file. */
+  get filePath() {
+    return this.filepath;
+  }
+  /** Patient's Name (0010,0010). */
+  get patientName() {
+    return this.dicomDataset.patientName;
+  }
+  /** Patient ID (0010,0020). */
+  get patientID() {
+    return this.dicomDataset.patientID;
+  }
+  /** Study Date (0008,0020). */
+  get studyDate() {
+    return this.dicomDataset.studyDate;
+  }
+  /** Modality (0008,0060). */
+  get modality() {
+    return this.dicomDataset.modality;
+  }
+  /** Accession Number (0008,0050). */
+  get accession() {
+    return this.dicomDataset.accession;
+  }
+  /** SOP Class UID (0008,0016). */
+  get sopClassUID() {
+    return this.dicomDataset.sopClassUID;
+  }
+  /** Study Instance UID (0020,000D). */
+  get studyInstanceUID() {
+    return this.dicomDataset.studyInstanceUID;
+  }
+  /** Series Instance UID (0020,000E). */
+  get seriesInstanceUID() {
+    return this.dicomDataset.seriesInstanceUID;
+  }
+  /** SOP Instance UID (0008,0018). */
+  get sopInstanceUID() {
+    return this.dicomDataset.sopInstanceUID;
+  }
+  /** Transfer Syntax UID (0002,0010). */
+  get transferSyntaxUID() {
+    return this.dicomDataset.transferSyntaxUID;
+  }
+  /**
+   * Gets a tag value as a string with optional fallback.
+   *
+   * @param tag - A DICOM tag, e.g. `'(0010,0010)'` or `'00100010'`
+   * @param fallback - Value to return if tag is missing (default: `''`)
+   */
+  getString(tag2, fallback = "") {
+    return this.dicomDataset.getString(tag2, fallback);
+  }
+  /**
+   * Gets a tag value as a number.
+   *
+   * @param tag - A DICOM tag, e.g. `'(0020,0013)'`
+   */
+  getNumber(tag2) {
+    return this.dicomDataset.getNumber(tag2);
+  }
+  /** Checks whether a tag exists in the dataset. */
+  hasTag(tag2) {
+    return this.dicomDataset.hasTag(tag2);
+  }
+  /**
+   * Finds all values matching a wildcard path.
+   *
+   * @param path - A DicomTagPath with optional wildcard indices
+   */
+  findValues(path2) {
+    return this.dicomDataset.findValues(path2);
+  }
+  // -----------------------------------------------------------------------
+  // Write methods (return new instance)
+  // -----------------------------------------------------------------------
+  /**
+   * Sets a tag value, returning a new DicomInstance.
+   *
+   * @param path - The DICOM tag path (e.g. `'(0010,0010)'`)
+   * @param value - The new value
+   */
+  setTag(path2, value) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.setTag(path2, value), this.filepath, this.meta);
+  }
+  /**
+   * Erases a tag, returning a new DicomInstance.
+   *
+   * @param path - The DICOM tag path to erase
+   */
+  eraseTag(path2) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.eraseTag(path2), this.filepath, this.meta);
+  }
+  /** Erases all private tags, returning a new DicomInstance. */
+  erasePrivateTags() {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.erasePrivateTags(), this.filepath, this.meta);
+  }
+  /** Sets Patient's Name (0010,0010). */
+  setPatientName(value) {
+    return this.setTag("(0010,0010)", value);
+  }
+  /** Sets Patient ID (0010,0020). */
+  setPatientID(value) {
+    return this.setTag("(0010,0020)", value);
+  }
+  /** Sets Study Date (0008,0020). */
+  setStudyDate(value) {
+    return this.setTag("(0008,0020)", value);
+  }
+  /** Sets Modality (0008,0060). */
+  setModality(value) {
+    return this.setTag("(0008,0060)", value);
+  }
+  /** Sets Accession Number (0008,0050). */
+  setAccessionNumber(value) {
+    return this.setTag("(0008,0050)", value);
+  }
+  /** Sets Study Description (0008,1030). */
+  setStudyDescription(value) {
+    return this.setTag("(0008,1030)", value);
+  }
+  /** Sets Series Description (0008,103E). */
+  setSeriesDescription(value) {
+    return this.setTag("(0008,103E)", value);
+  }
+  /** Sets Institution Name (0008,0080). */
+  setInstitutionName(value) {
+    return this.setTag("(0008,0080)", value);
+  }
+  /**
+   * Transforms a tag value using a function.
+   *
+   * The function receives the current string value (or undefined if tag is missing)
+   * and returns the new value. Returns a new DicomInstance with the modification.
+   *
+   * @param path - The DICOM tag path
+   * @param fn - Transform function receiving the current value
+   */
+  transformTag(path2, fn) {
+    const current = this.dicomDataset.getString(path2);
+    const newValue = fn(current.length > 0 ? current : void 0);
+    return this.setTag(path2, newValue);
+  }
+  /**
+   * Sets multiple tags at once, returning a new DicomInstance.
+   *
+   * @param entries - A record of tag path → value pairs
+   */
+  setBatch(entries) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.setBatch(entries), this.filepath, this.meta);
+  }
+  /**
+   * Returns a new DicomInstance with the given changes merged into pending changes.
+   *
+   * @param changes - A ChangeSet to merge with existing pending changes
+   * @returns A new DicomInstance with accumulated changes
+   */
+  withChanges(changes) {
+    return new _DicomInstance(this.dicomDataset, this.changeSet.merge(changes), this.filepath, this.meta);
+  }
+  /**
+   * Returns a new DicomInstance pointing to a different file path.
+   *
+   * Preserves the dataset, pending changes, and metadata.
+   *
+   * @param newPath - The new filesystem path (validated via createDicomFilePath)
+   * @returns A new DicomInstance with the updated path
+   * @throws If the path is invalid
+   */
+  withFilePath(newPath) {
+    const result = createDicomFilePath(newPath);
+    if (!result.ok) throw result.error;
+    return new _DicomInstance(this.dicomDataset, this.changeSet, result.value, this.meta);
+  }
+  // -----------------------------------------------------------------------
+  // File I/O
+  // -----------------------------------------------------------------------
+  /**
+   * Applies pending changes to the file in-place.
+   *
+   * Requires that the instance has an associated file path.
+   *
+   * @param options - Timeout and abort options
+   */
+  async applyChanges(options) {
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    if (this.changeSet.isEmpty) return ok(void 0);
+    return applyModifications(this.filepath, this.changeSet, options ?? {});
+  }
+  /**
+   * Copies the file to a new path and applies pending changes to the copy.
+   *
+   * Returns a new DicomInstance pointing to the output path.
+   *
+   * @param outputPath - Destination filesystem path
+   * @param options - Timeout and abort options
+   */
+  async writeAs(outputPath, options) {
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    const outPathResult = createDicomFilePath(outputPath);
+    if (!outPathResult.ok) return err(outPathResult.error);
+    const copyResult = await copyFileSafe(this.filepath, outputPath);
+    if (!copyResult.ok) return err(copyResult.error);
+    if (!this.changeSet.isEmpty) {
+      const applyResult = await applyModifications(outPathResult.value, this.changeSet, options ?? {});
+      if (!applyResult.ok) {
+        await unlinkFile(outputPath);
+        return err(applyResult.error);
+      }
+    }
+    return ok(new _DicomInstance(this.dicomDataset, ChangeSet.empty(), outPathResult.value, this.meta));
+  }
+  /**
+   * Gets the file size in bytes.
+   *
+   * @returns A Result containing the size or an error
+   */
+  async fileSize() {
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    return statFileSize(this.filepath);
+  }
+  /**
+   * Deletes the associated file from the filesystem.
+   *
+   * @returns A Result indicating success or failure
+   */
+  async unlink() {
+    if (this.filepath === void 0) return err(new Error("No file path associated with this instance"));
+    return unlinkFile(this.filepath);
+  }
+  // -----------------------------------------------------------------------
+  // Metadata (non-DICOM app context)
+  // -----------------------------------------------------------------------
+  /**
+   * Returns a new DicomInstance with application metadata attached.
+   *
+   * Metadata is not stored in the DICOM file — it's for application context
+   * (e.g. tracking source association, processing status, etc.).
+   *
+   * @param key - Metadata key
+   * @param value - Metadata value
+   */
+  withMetadata(key, value) {
+    const newMeta = new Map(this.meta);
+    newMeta.set(key, value);
+    return new _DicomInstance(this.dicomDataset, this.changeSet, this.filepath, newMeta);
+  }
+  /**
+   * Gets application metadata by key.
+   *
+   * @param key - Metadata key
+   * @returns The metadata value or undefined
+   */
+  getMetadata(key) {
+    return this.meta.get(key);
+  }
+};
 
 // src/events/dcmrecv.ts
 var DcmrecvEvent = {
@@ -33593,7 +33937,11 @@ var DcmrecvEvent = {
   ASSOCIATION_ABORTED: "ASSOCIATION_ABORTED",
   ECHO_REQUEST: "ECHO_REQUEST",
   CANNOT_START_LISTENER: "CANNOT_START_LISTENER",
-  REFUSING_ASSOCIATION: "REFUSING_ASSOCIATION"
+  REFUSING_ASSOCIATION: "REFUSING_ASSOCIATION",
+  /** Synthetic: STORED_FILE enriched with association context. */
+  FILE_RECEIVED: "FILE_RECEIVED",
+  /** Synthetic: emitted on association release/abort with summary. */
+  ASSOCIATION_COMPLETE: "ASSOCIATION_COMPLETE"
 };
 var DCMRECV_PATTERNS = [
   {
@@ -33603,9 +33951,9 @@ var DCMRECV_PATTERNS = [
   },
   {
     event: DcmrecvEvent.ASSOCIATION_RECEIVED,
-    pattern: /Association Received\s{1,100}([^:]+):\s*"([^"]+)"\s*->\s*"([^"]+)"/,
+    pattern: /Association Received\s{1,100}(\S+):\s+(\S+)\s+->\s+(\S+)/,
     processor: (match) => ({
-      address: match[1] ?? "",
+      source: match[1] ?? "",
       callingAE: match[2] ?? "",
       calledAE: match[3] ?? ""
     })
@@ -33633,7 +33981,7 @@ var DCMRECV_PATTERNS = [
   },
   {
     event: DcmrecvEvent.ASSOCIATION_RELEASE,
-    pattern: /Received Association Release/i,
+    pattern: /Association Release/i,
     processor: () => void 0
   },
   {
@@ -33669,6 +34017,11 @@ var StorescpEvent = {
   STORING_FILE: "STORING_FILE",
   SUBDIRECTORY_CREATED: "SUBDIRECTORY_CREATED"
 };
+var STORESCP_ASSOCIATION_RECEIVED = {
+  event: StorescpEvent.ASSOCIATION_RECEIVED,
+  pattern: /Association Received/i,
+  processor: () => ({ source: "", callingAE: "", calledAE: "" })
+};
 var STORESCP_ADDITIONAL_PATTERNS = [
   {
     event: StorescpEvent.STORING_FILE,
@@ -33685,7 +34038,11 @@ var STORESCP_ADDITIONAL_PATTERNS = [
     })
   }
 ];
-var STORESCP_PATTERNS = [...DCMRECV_PATTERNS, ...STORESCP_ADDITIONAL_PATTERNS];
+var STORESCP_PATTERNS = [
+  ...DCMRECV_PATTERNS.filter((p) => p.event !== DcmrecvEvent.ASSOCIATION_RECEIVED),
+  STORESCP_ASSOCIATION_RECEIVED,
+  ...STORESCP_ADDITIONAL_PATTERNS
+];
 var STORESCP_FATAL_EVENTS = /* @__PURE__ */ new Set([...DCMRECV_FATAL_EVENTS]);
 
 // src/events/dcmprscp.ts
@@ -33992,6 +34349,97 @@ var WLMSCPFS_PATTERNS = [
   }
 ];
 var WLMSCPFS_FATAL_EVENTS = /* @__PURE__ */ new Set([WlmscpfsEvent.CANNOT_START_LISTENER]);
+
+// src/servers/AssociationTracker.ts
+var AssociationTracker = class {
+  constructor() {
+    __publicField(this, "association");
+    __publicField(this, "counter", 0);
+  }
+  /**
+   * Begins a new association, transitioning from IDLE to ACTIVE.
+   *
+   * If an association is already active, it is silently ended (abort)
+   * and the new one begins.
+   *
+   * @param data - Association metadata
+   * @returns The unique association ID
+   */
+  beginAssociation(data) {
+    this.counter++;
+    const associationId = `assoc-${String(this.counter)}`;
+    this.association = {
+      associationId,
+      callingAE: data.callingAE,
+      calledAE: data.calledAE,
+      source: data.source,
+      startTime: Date.now(),
+      files: []
+    };
+    return associationId;
+  }
+  /**
+   * Tracks a file received during the current association.
+   *
+   * If no association is active, returns a TrackedFile with empty context.
+   *
+   * @param filePath - Path to the received file
+   * @returns A TrackedFile enriched with association context
+   */
+  trackFile(filePath) {
+    if (this.association === void 0) {
+      return {
+        filePath,
+        associationId: "",
+        callingAE: "",
+        calledAE: "",
+        source: ""
+      };
+    }
+    this.association.files.push(filePath);
+    return {
+      filePath,
+      associationId: this.association.associationId,
+      callingAE: this.association.callingAE,
+      calledAE: this.association.calledAE,
+      source: this.association.source
+    };
+  }
+  /**
+   * Ends the current association, transitioning from ACTIVE to IDLE.
+   *
+   * @param reason - Why the association ended
+   * @returns An AssociationSummary, or undefined if no association was active
+   */
+  endAssociation(reason) {
+    if (this.association === void 0) return void 0;
+    const summary = {
+      associationId: this.association.associationId,
+      callingAE: this.association.callingAE,
+      calledAE: this.association.calledAE,
+      source: this.association.source,
+      files: [...this.association.files],
+      durationMs: Date.now() - this.association.startTime,
+      endReason: reason
+    };
+    this.association = void 0;
+    return summary;
+  }
+  /** The currently active association context, or undefined. */
+  get current() {
+    return this.association;
+  }
+  /** Whether an association is currently active. */
+  get isActive() {
+    return this.association !== void 0;
+  }
+  /** Resets the tracker to IDLE, discarding any active association. */
+  reset() {
+    this.association = void 0;
+  }
+};
+
+// src/servers/Dcmrecv.ts
 var SubdirectoryMode = {
   NONE: "none",
   SERIES_DATE: "series-date"
@@ -34078,10 +34526,13 @@ var Dcmrecv = class _Dcmrecv extends DcmtkProcess {
   constructor(config, parser2, signal) {
     super(config);
     __publicField(this, "parser");
+    __publicField(this, "tracker");
     __publicField(this, "abortSignal");
     __publicField(this, "abortHandler");
     this.parser = parser2;
+    this.tracker = new AssociationTracker();
     this.wireParser();
+    this.wireTracker();
     if (signal !== void 0) {
       this.wireAbortSignal(signal);
     }
@@ -34122,6 +34573,24 @@ var Dcmrecv = class _Dcmrecv extends DcmtkProcess {
   onStoredFile(listener) {
     return this.onEvent("STORED_FILE", listener);
   }
+  /**
+   * Registers a listener for received files enriched with association context.
+   *
+   * @param listener - Callback receiving tracked file data
+   * @returns this for chaining
+   */
+  onFileReceived(listener) {
+    return this.onEvent("FILE_RECEIVED", listener);
+  }
+  /**
+   * Registers a listener for completed associations.
+   *
+   * @param listener - Callback receiving association summary
+   * @returns this for chaining
+   */
+  onAssociationComplete(listener) {
+    return this.onEvent("ASSOCIATION_COMPLETE", listener);
+  }
   /**
    * Creates a new Dcmrecv server instance.
    *
@@ -34131,7 +34600,7 @@ var Dcmrecv = class _Dcmrecv extends DcmtkProcess {
   static create(options) {
     const validation = DcmrecvOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`dcmrecv: invalid options: ${validation.error.message}`));
+      return err(createValidationError("dcmrecv", validation.error));
     }
     const binaryResult = resolveBinary("dcmrecv");
     if (!binaryResult.ok) {
@@ -34164,7 +34633,29 @@ var Dcmrecv = class _Dcmrecv extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
+    });
+  }
+  /** Wires the AssociationTracker to server events. */
+  wireTracker() {
+    this.onEvent("ASSOCIATION_RECEIVED", (data) => {
+      this.tracker.beginAssociation(data);
+    });
+    this.onEvent("STORED_FILE", (data) => {
+      const tracked = this.tracker.trackFile(data.filePath);
+      this.emit(DcmrecvEvent.FILE_RECEIVED, tracked);
+    });
+    this.onEvent("ASSOCIATION_RELEASE", () => {
+      const summary = this.tracker.endAssociation("release");
+      if (summary !== void 0) {
+        this.emit(DcmrecvEvent.ASSOCIATION_COMPLETE, summary);
+      }
+    });
+    this.onEvent("ASSOCIATION_ABORTED", () => {
+      const summary = this.tracker.endAssociation("abort");
+      if (summary !== void 0) {
+        this.emit(DcmrecvEvent.ASSOCIATION_COMPLETE, summary);
+      }
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34312,21 +34803,17 @@ var StoreSCP = class _StoreSCP extends DcmtkProcess {
   constructor(config, parser2, signal) {
     super(config);
     __publicField(this, "parser");
+    __publicField(this, "tracker");
     __publicField(this, "abortSignal");
     __publicField(this, "abortHandler");
     this.parser = parser2;
+    this.tracker = new AssociationTracker();
     this.wireParser();
+    this.wireTracker();
     if (signal !== void 0) {
       this.wireAbortSignal(signal);
     }
   }
-  /**
-   * Registers a typed listener for a storescp-specific event.
-   *
-   * @param event - The event name from StoreSCPEventMap
-   * @param listener - Callback receiving typed event data
-   * @returns this for chaining
-   */
   /** Disposes the server and its parser, preventing listener leaks. */
   [Symbol.dispose]() {
     if (this.abortSignal !== void 0 && this.abortHandler !== void 0) {
@@ -34335,6 +34822,13 @@ var StoreSCP = class _StoreSCP extends DcmtkProcess {
     this.parser[Symbol.dispose]();
     super[Symbol.dispose]();
   }
+  /**
+   * Registers a typed listener for a storescp-specific event.
+   *
+   * @param event - The event name from StoreSCPEventMap
+   * @param listener - Callback receiving typed event data
+   * @returns this for chaining
+   */
   onEvent(event, listener) {
     return this.on(event, listener);
   }
@@ -34356,6 +34850,24 @@ var StoreSCP = class _StoreSCP extends DcmtkProcess {
   onStoringFile(listener) {
     return this.onEvent("STORING_FILE", listener);
   }
+  /**
+   * Registers a listener for received files enriched with association context.
+   *
+   * @param listener - Callback receiving tracked file data
+   * @returns this for chaining
+   */
+  onFileReceived(listener) {
+    return this.onEvent("FILE_RECEIVED", listener);
+  }
+  /**
+   * Registers a listener for completed associations.
+   *
+   * @param listener - Callback receiving association summary
+   * @returns this for chaining
+   */
+  onAssociationComplete(listener) {
+    return this.onEvent("ASSOCIATION_COMPLETE", listener);
+  }
   /**
    * Creates a new StoreSCP server instance.
    *
@@ -34365,7 +34877,7 @@ var StoreSCP = class _StoreSCP extends DcmtkProcess {
   static create(options) {
     const validation = StoreSCPOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`storescp: invalid options: ${validation.error.message}`));
+      return err(createValidationError("storescp", validation.error));
     }
     const binaryResult = resolveBinary("storescp");
     if (!binaryResult.ok) {
@@ -34398,7 +34910,33 @@ var StoreSCP = class _StoreSCP extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
+    });
+  }
+  /** Wires the AssociationTracker to server events. */
+  wireTracker() {
+    this.onEvent("ASSOCIATION_RECEIVED", (data) => {
+      this.tracker.beginAssociation(data);
+    });
+    this.onEvent("STORING_FILE", (data) => {
+      const tracked = this.tracker.trackFile(data.filePath);
+      this.emit(DcmrecvEvent.FILE_RECEIVED, tracked);
+    });
+    this.onEvent("STORED_FILE", (data) => {
+      const tracked = this.tracker.trackFile(data.filePath);
+      this.emit(DcmrecvEvent.FILE_RECEIVED, tracked);
+    });
+    this.onEvent("ASSOCIATION_RELEASE", () => {
+      const summary = this.tracker.endAssociation("release");
+      if (summary !== void 0) {
+        this.emit(DcmrecvEvent.ASSOCIATION_COMPLETE, summary);
+      }
+    });
+    this.onEvent("ASSOCIATION_ABORTED", () => {
+      const summary = this.tracker.endAssociation("abort");
+      if (summary !== void 0) {
+        this.emit(DcmrecvEvent.ASSOCIATION_COMPLETE, summary);
+      }
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34497,7 +35035,7 @@ var DcmprsCP = class _DcmprsCP extends DcmtkProcess {
   static create(options) {
     const validation = DcmprsCPOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`dcmprscp: invalid options: ${validation.error.message}`));
+      return err(createValidationError("dcmprscp", validation.error));
     }
     const binaryResult = resolveBinary("dcmprscp");
     if (!binaryResult.ok) {
@@ -34530,7 +35068,7 @@ var DcmprsCP = class _DcmprsCP extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34626,7 +35164,7 @@ var Dcmpsrcv = class _Dcmpsrcv extends DcmtkProcess {
   static create(options) {
     const validation = DcmpsrcvOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`dcmpsrcv: invalid options: ${validation.error.message}`));
+      return err(createValidationError("dcmpsrcv", validation.error));
     }
     const binaryResult = resolveBinary("dcmpsrcv");
     if (!binaryResult.ok) {
@@ -34659,7 +35197,7 @@ var Dcmpsrcv = class _Dcmpsrcv extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34737,13 +35275,6 @@ var DcmQRSCP = class _DcmQRSCP extends DcmtkProcess {
       this.wireAbortSignal(signal);
     }
   }
-  /**
-   * Registers a typed listener for a dcmqrscp-specific event.
-   *
-   * @param event - The event name from DcmQRSCPEventMap
-   * @param listener - Callback receiving typed event data
-   * @returns this for chaining
-   */
   /** Disposes the server and its parser, preventing listener leaks. */
   [Symbol.dispose]() {
     if (this.abortSignal !== void 0 && this.abortHandler !== void 0) {
@@ -34752,6 +35283,13 @@ var DcmQRSCP = class _DcmQRSCP extends DcmtkProcess {
     this.parser[Symbol.dispose]();
     super[Symbol.dispose]();
   }
+  /**
+   * Registers a typed listener for a dcmqrscp-specific event.
+   *
+   * @param event - The event name from DcmQRSCPEventMap
+   * @param listener - Callback receiving typed event data
+   * @returns this for chaining
+   */
   onEvent(event, listener) {
     return this.on(event, listener);
   }
@@ -34782,7 +35320,7 @@ var DcmQRSCP = class _DcmQRSCP extends DcmtkProcess {
   static create(options) {
     const validation = DcmQRSCPOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`dcmqrscp: invalid options: ${validation.error.message}`));
+      return err(createValidationError("dcmqrscp", validation.error));
     }
     const binaryResult = resolveBinary("dcmqrscp");
     if (!binaryResult.ok) {
@@ -34814,7 +35352,7 @@ var DcmQRSCP = class _DcmQRSCP extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34884,13 +35422,6 @@ var Wlmscpfs = class _Wlmscpfs extends DcmtkProcess {
       this.wireAbortSignal(signal);
     }
   }
-  /**
-   * Registers a typed listener for a wlmscpfs-specific event.
-   *
-   * @param event - The event name from WlmscpfsEventMap
-   * @param listener - Callback receiving typed event data
-   * @returns this for chaining
-   */
   /** Disposes the server and its parser, preventing listener leaks. */
   [Symbol.dispose]() {
     if (this.abortSignal !== void 0 && this.abortHandler !== void 0) {
@@ -34899,6 +35430,13 @@ var Wlmscpfs = class _Wlmscpfs extends DcmtkProcess {
     this.parser[Symbol.dispose]();
     super[Symbol.dispose]();
   }
+  /**
+   * Registers a typed listener for a wlmscpfs-specific event.
+   *
+   * @param event - The event name from WlmscpfsEventMap
+   * @param listener - Callback receiving typed event data
+   * @returns this for chaining
+   */
   onEvent(event, listener) {
     return this.on(event, listener);
   }
@@ -34929,7 +35467,7 @@ var Wlmscpfs = class _Wlmscpfs extends DcmtkProcess {
   static create(options) {
     const validation = WlmscpfsOptionsSchema.safeParse(options);
     if (!validation.success) {
-      return err(new Error(`wlmscpfs: invalid options: ${validation.error.message}`));
+      return err(createValidationError("wlmscpfs", validation.error));
     }
     const binaryResult = resolveBinary("wlmscpfs");
     if (!binaryResult.ok) {
@@ -34962,7 +35500,7 @@ var Wlmscpfs = class _Wlmscpfs extends DcmtkProcess {
         this.emit("error", { error: new Error(`Fatal: ${event}`), fatal: true });
         void this.stop();
       }
-      this.emit(event, ...[data]);
+      this.emit(event, data);
     });
   }
   /** Wires an AbortSignal to stop the server. */
@@ -34978,6 +35516,506 @@ var Wlmscpfs = class _Wlmscpfs extends DcmtkProcess {
     signal.addEventListener("abort", this.abortHandler, { once: true });
   }
 };
+var DEFAULT_MIN_POOL_SIZE = 2;
+var DEFAULT_MAX_POOL_SIZE = 10;
+var DEFAULT_CONNECTION_TIMEOUT_MS = 1e4;
+var CONNECTION_RETRY_INTERVAL_MS = 500;
+var MAX_CONNECTION_RETRIES = 200;
+var DicomReceiverOptionsSchema = zod.z.object({
+  port: zod.z.number().int().min(1).max(65535),
+  storageDir: zod.z.string().min(1).refine(isSafePath, { message: "path traversal detected in storageDir" }),
+  aeTitle: zod.z.string().min(1).max(16).refine(isValidAETitle, { message: "AE Title contains invalid characters" }).optional(),
+  minPoolSize: zod.z.number().int().min(1).max(100).optional(),
+  maxPoolSize: zod.z.number().int().min(1).max(100).optional(),
+  connectionTimeoutMs: zod.z.number().int().positive().optional(),
+  configFile: zod.z.string().min(1).refine(isSafePath, { message: "path traversal detected in configFile" }).optional(),
+  configProfile: zod.z.string().min(1).optional(),
+  signal: zod.z.instanceof(AbortSignal).optional()
+}).strict().refine((data) => (data.minPoolSize ?? DEFAULT_MIN_POOL_SIZE) <= (data.maxPoolSize ?? DEFAULT_MAX_POOL_SIZE), {
+  message: "minPoolSize must be <= maxPoolSize"
+});
+function allocatePort() {
+  return new Promise((resolve) => {
+    const server = net__namespace.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr === null || typeof addr === "string") {
+        server.close(() => resolve(err(new Error("Failed to allocate port"))));
+        return;
+      }
+      const port = addr.port;
+      server.close(() => resolve(ok(port)));
+    });
+    server.on("error", (e) => {
+      resolve(err(new Error(`Port allocation failed: ${e.message}`)));
+    });
+  });
+}
+var DicomReceiver = class _DicomReceiver extends events.EventEmitter {
+  constructor(options) {
+    super();
+    __publicField(this, "options");
+    __publicField(this, "minPoolSize");
+    __publicField(this, "maxPoolSize");
+    __publicField(this, "connectionTimeoutMs");
+    __publicField(this, "workers", /* @__PURE__ */ new Map());
+    __publicField(this, "tcpServer");
+    __publicField(this, "associationCounter", 0);
+    __publicField(this, "started", false);
+    __publicField(this, "stopping", false);
+    __publicField(this, "abortHandler");
+    this.setMaxListeners(20);
+    this.on("error", () => {
+    });
+    this.options = options;
+    this.minPoolSize = options.minPoolSize ?? DEFAULT_MIN_POOL_SIZE;
+    this.maxPoolSize = options.maxPoolSize ?? DEFAULT_MAX_POOL_SIZE;
+    this.connectionTimeoutMs = options.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /**
+   * Creates a new DicomReceiver instance.
+   *
+   * @param options - Configuration options
+   * @returns A Result containing the instance or a validation error
+   */
+  static create(options) {
+    const validation = DicomReceiverOptionsSchema.safeParse(options);
+    if (!validation.success) {
+      return err(createValidationError("DicomReceiver", validation.error));
+    }
+    return ok(new _DicomReceiver(options));
+  }
+  /**
+   * Starts the TCP proxy and spawns the initial worker pool.
+   *
+   * @returns A Result indicating success or failure
+   */
+  async start() {
+    if (this.started) {
+      return err(new Error("DicomReceiver: already started"));
+    }
+    this.started = true;
+    const storageDirResult = await ensureDirectory(this.options.storageDir);
+    if (!storageDirResult.ok) return storageDirResult;
+    const spawnResults = await this.spawnWorkers(this.minPoolSize);
+    if (!spawnResults.ok) return spawnResults;
+    const listenResult = await this.startTcpProxy();
+    if (!listenResult.ok) return listenResult;
+    if (this.options.signal !== void 0) {
+      this.wireAbortSignal(this.options.signal);
+    }
+    return ok(void 0);
+  }
+  /**
+   * Stops the TCP proxy and all workers.
+   */
+  async stop() {
+    if (!this.started || this.stopping) {
+      return;
+    }
+    this.stopping = true;
+    if (this.options.signal !== void 0 && this.abortHandler !== void 0) {
+      this.options.signal.removeEventListener("abort", this.abortHandler);
+    }
+    await this.closeTcpProxy();
+    const stopPromises = [];
+    for (const worker of this.workers.values()) {
+      stopPromises.push(this.stopWorker(worker));
+    }
+    await Promise.all(stopPromises);
+    this.workers.clear();
+    this.started = false;
+    this.stopping = false;
+  }
+  /**
+   * Registers a typed listener for a DicomReceiver-specific event.
+   *
+   * @param event - The event name from DicomReceiverEventMap
+   * @param listener - Callback receiving typed event data
+   * @returns this for chaining
+   */
+  onEvent(event, listener) {
+    return this.on(event, listener);
+  }
+  /**
+   * Registers a listener for received files.
+   *
+   * @param listener - Callback receiving file data
+   * @returns this for chaining
+   */
+  onFileReceived(listener) {
+    return this.on("FILE_RECEIVED", listener);
+  }
+  /**
+   * Registers a listener for completed associations.
+   *
+   * @param listener - Callback receiving association data
+   * @returns this for chaining
+   */
+  onAssociationComplete(listener) {
+    return this.on("ASSOCIATION_COMPLETE", listener);
+  }
+  /** Current pool status. */
+  get poolStatus() {
+    let idle = 0;
+    let busy = 0;
+    for (const w of this.workers.values()) {
+      if (w.state === "idle") idle++;
+      else busy++;
+    }
+    return { idle, busy, total: this.workers.size };
+  }
+  // -----------------------------------------------------------------------
+  // TCP proxy
+  // -----------------------------------------------------------------------
+  /** Starts the TCP proxy on the configured port. */
+  startTcpProxy() {
+    return new Promise((resolve) => {
+      this.tcpServer = net__namespace.createServer((socket) => {
+        void this.handleConnection(socket);
+      });
+      this.tcpServer.on("error", (e) => {
+        if (!this.started) {
+          resolve(err(new Error(`DicomReceiver: TCP proxy failed: ${e.message}`)));
+        } else {
+          this.emit("error", { error: e instanceof Error ? e : new Error(String(e)) });
+        }
+      });
+      this.tcpServer.listen(this.options.port, () => {
+        resolve(ok(void 0));
+      });
+    });
+  }
+  /** Closes the TCP proxy server. */
+  closeTcpProxy() {
+    return new Promise((resolve) => {
+      if (this.tcpServer === void 0) {
+        resolve();
+        return;
+      }
+      this.tcpServer.close(() => resolve());
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Connection routing
+  // -----------------------------------------------------------------------
+  /** Routes an incoming connection to an idle worker. */
+  async handleConnection(remoteSocket) {
+    remoteSocket.pause();
+    const worker = await this.findIdleWorker();
+    if (worker === void 0) {
+      remoteSocket.destroy(new Error("DicomReceiver: no idle worker available"));
+      this.emit("error", { error: new Error("DicomReceiver: connection rejected \u2014 pool exhausted") });
+      return;
+    }
+    this.associationCounter++;
+    const associationId = `assoc-${String(this.associationCounter)}`;
+    const associationDir = path__namespace.join(this.options.storageDir, associationId);
+    const mkdirResult = await ensureDirectory(associationDir);
+    if (!mkdirResult.ok) {
+      remoteSocket.destroy();
+      this.emit("error", { error: mkdirResult.error });
+      return;
+    }
+    worker.state = "busy";
+    worker.associationId = associationId;
+    worker.associationDir = associationDir;
+    worker.files = [];
+    worker.fileSizes = [];
+    worker.startAt = Date.now();
+    this.pipeConnection(worker, remoteSocket);
+    void this.replenishPool();
+  }
+  /** Finds an idle worker, retrying up to connectionTimeoutMs. */
+  async findIdleWorker() {
+    const idle = this.getIdleWorker();
+    if (idle !== void 0) return idle;
+    const maxRetries = Math.min(Math.ceil(this.connectionTimeoutMs / CONNECTION_RETRY_INTERVAL_MS), MAX_CONNECTION_RETRIES);
+    for (let i = 0; i < maxRetries; i++) {
+      await delay(CONNECTION_RETRY_INTERVAL_MS);
+      const found = this.getIdleWorker();
+      if (found !== void 0) return found;
+      if (this.stopping) return void 0;
+    }
+    return void 0;
+  }
+  /** Returns the first idle worker, or undefined. */
+  getIdleWorker() {
+    for (const w of this.workers.values()) {
+      if (w.state === "idle") return w;
+    }
+    return void 0;
+  }
+  /** Pipes remote socket bidirectionally to the worker's port. */
+  pipeConnection(worker, remoteSocket) {
+    const workerSocket = net__namespace.createConnection({ port: worker.port, host: "127.0.0.1" });
+    worker.remoteSocket = remoteSocket;
+    worker.workerSocket = workerSocket;
+    remoteSocket.pipe(workerSocket);
+    workerSocket.pipe(remoteSocket);
+    remoteSocket.resume();
+    const cleanup = () => {
+      remoteSocket.unpipe(workerSocket);
+      workerSocket.unpipe(remoteSocket);
+      if (!remoteSocket.destroyed) remoteSocket.destroy();
+      if (!workerSocket.destroyed) workerSocket.destroy();
+    };
+    remoteSocket.on("error", cleanup);
+    workerSocket.on("error", cleanup);
+    remoteSocket.on("close", cleanup);
+    workerSocket.on("close", cleanup);
+  }
+  // -----------------------------------------------------------------------
+  // Worker pool management
+  // -----------------------------------------------------------------------
+  /** Spawns `count` new workers and adds them to the pool. */
+  async spawnWorkers(count) {
+    const promises = [];
+    for (let i = 0; i < count; i++) {
+      promises.push(this.spawnWorker());
+    }
+    const results = await Promise.all(promises);
+    for (const result of results) {
+      if (!result.ok) return err(result.error);
+    }
+    return ok(void 0);
+  }
+  /** Spawns a single Dcmrecv worker with an ephemeral port. */
+  async spawnWorker() {
+    const portResult = await allocatePort();
+    if (!portResult.ok) return portResult;
+    const port = portResult.value;
+    const tempDir = path__namespace.join(os__namespace.tmpdir(), `dcmrecv-pool-${String(port)}-${String(Date.now())}`);
+    const mkdirResult = await ensureDirectory(tempDir);
+    if (!mkdirResult.ok) return mkdirResult;
+    const createResult = Dcmrecv.create({
+      port,
+      aeTitle: this.options.aeTitle ?? "DCMRECV",
+      outputDirectory: tempDir,
+      configFile: this.options.configFile,
+      configProfile: this.options.configProfile
+    });
+    if (!createResult.ok) return createResult;
+    const dcmrecv = createResult.value;
+    const worker = {
+      dcmrecv,
+      port,
+      tempDir,
+      state: "idle",
+      associationId: void 0,
+      associationDir: void 0,
+      files: [],
+      fileSizes: [],
+      startAt: void 0,
+      remoteSocket: void 0,
+      workerSocket: void 0
+    };
+    this.wireWorkerEvents(worker);
+    const startResult = await dcmrecv.start();
+    if (!startResult.ok) {
+      return err(new Error(`DicomReceiver: worker start failed on port ${String(port)}: ${startResult.error.message}`));
+    }
+    this.workers.set(port, worker);
+    return ok(worker);
+  }
+  /** Stops a single worker: stop process, clean temp dir, remove from pool. */
+  async stopWorker(worker) {
+    if (worker.remoteSocket !== void 0 && !worker.remoteSocket.destroyed) {
+      worker.remoteSocket.destroy();
+    }
+    if (worker.workerSocket !== void 0 && !worker.workerSocket.destroyed) {
+      worker.workerSocket.destroy();
+    }
+    await worker.dcmrecv.stop();
+    worker.dcmrecv[Symbol.dispose]();
+    await removeDirSafe(worker.tempDir);
+    this.workers.delete(worker.port);
+  }
+  /** Pre-emptively spawns workers to keep idle count >= minPoolSize. */
+  async replenishPool() {
+    const status = this.poolStatus;
+    const needed = this.minPoolSize - status.idle;
+    const capacity = this.maxPoolSize - status.total;
+    const toSpawn = Math.min(needed, capacity);
+    if (toSpawn <= 0) return;
+    const promises = [];
+    for (let i = 0; i < toSpawn; i++) {
+      promises.push(this.spawnWorker());
+    }
+    const results = await Promise.all(promises);
+    for (const result of results) {
+      if (!result.ok) {
+        this.emit("error", { error: result.error });
+      }
+    }
+  }
+  /** Stops excess idle workers when idle count > minPoolSize + 2. */
+  async scaleDown() {
+    const idleWorkers = [];
+    for (const w of this.workers.values()) {
+      if (w.state === "idle") idleWorkers.push(w);
+    }
+    const excess = idleWorkers.length - (this.minPoolSize + 2);
+    if (excess <= 0) return;
+    const toStop = idleWorkers.slice(0, excess);
+    const promises = [];
+    for (const w of toStop) {
+      promises.push(this.stopWorker(w));
+    }
+    await Promise.all(promises);
+  }
+  // -----------------------------------------------------------------------
+  // Worker event wiring
+  // -----------------------------------------------------------------------
+  /** Wires FILE_RECEIVED and ASSOCIATION_COMPLETE events on a worker. */
+  wireWorkerEvents(worker) {
+    this.wireFileReceived(worker);
+    this.wireAssociationComplete(worker);
+  }
+  /** Wires FILE_RECEIVED from dcmrecv worker to handleFileReceived. */
+  wireFileReceived(worker) {
+    worker.dcmrecv.onFileReceived((data) => {
+      void this.handleFileReceived(worker, data);
+    });
+  }
+  /** Moves a received file, opens it as DicomInstance, and emits FILE_RECEIVED. */
+  async handleFileReceived(worker, data) {
+    if (worker.associationDir === void 0 || worker.associationId === void 0) return;
+    const srcPath = data.filePath;
+    const destPath = path__namespace.join(worker.associationDir, path__namespace.basename(srcPath));
+    const assocId = worker.associationId;
+    const assocDir = worker.associationDir;
+    const moveResult = await moveFile(srcPath, destPath);
+    const finalPath = moveResult.ok ? destPath : srcPath;
+    worker.files.push(finalPath);
+    worker.fileSizes.push(await statFileSafe(finalPath));
+    const openResult = await DicomInstance.open(finalPath);
+    if (!openResult.ok) {
+      this.emit("error", {
+        error: openResult.error,
+        filePath: finalPath,
+        associationId: assocId,
+        associationDir: assocDir,
+        callingAE: data.callingAE,
+        calledAE: data.calledAE,
+        source: data.source
+      });
+      return;
+    }
+    this.emit("FILE_RECEIVED", {
+      filePath: finalPath,
+      associationId: assocId,
+      associationDir: assocDir,
+      callingAE: data.callingAE,
+      calledAE: data.calledAE,
+      source: data.source,
+      instance: openResult.value
+    });
+  }
+  /** Returns worker to idle pool on association complete, emits summary. */
+  wireAssociationComplete(worker) {
+    worker.dcmrecv.onAssociationComplete((data) => {
+      const assocId = worker.associationId ?? data.associationId;
+      const assocDir = worker.associationDir ?? "";
+      const files = [...worker.files];
+      const endAt = Date.now();
+      const startAt = worker.startAt ?? endAt;
+      const totalBytes = sumArray(worker.fileSizes);
+      const elapsedMs = endAt - startAt;
+      const bytesPerSecond = elapsedMs > 0 ? Math.round(totalBytes / elapsedMs * 1e3) : 0;
+      this.emit("ASSOCIATION_COMPLETE", {
+        associationId: assocId,
+        associationDir: assocDir,
+        callingAE: data.callingAE,
+        calledAE: data.calledAE,
+        source: data.source,
+        files,
+        durationMs: data.durationMs,
+        endReason: data.endReason,
+        totalBytes,
+        bytesPerSecond,
+        startAt,
+        endAt
+      });
+      worker.state = "idle";
+      worker.associationId = void 0;
+      worker.associationDir = void 0;
+      worker.files = [];
+      worker.fileSizes = [];
+      worker.startAt = void 0;
+      worker.remoteSocket = void 0;
+      worker.workerSocket = void 0;
+      void this.scaleDown();
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Abort signal
+  // -----------------------------------------------------------------------
+  /** Wires an AbortSignal to stop the receiver. */
+  wireAbortSignal(signal) {
+    if (signal.aborted) {
+      void this.stop();
+      return;
+    }
+    this.abortHandler = () => {
+      void this.stop();
+    };
+    signal.addEventListener("abort", this.abortHandler, { once: true });
+  }
+};
+async function ensureDirectory(dirPath) {
+  try {
+    await fs__namespace.mkdir(dirPath, { recursive: true });
+    return ok(void 0);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return err(new Error(`Failed to create directory ${dirPath}: ${msg}`));
+  }
+}
+async function moveFile(src, dest) {
+  try {
+    await fs__namespace.rename(src, dest);
+    return ok(void 0);
+  } catch {
+    try {
+      await fs__namespace.copyFile(src, dest);
+      await fs__namespace.unlink(src);
+      return ok(void 0);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return err(new Error(`Failed to move file ${src} \u2192 ${dest}: ${msg}`));
+    }
+  }
+}
+async function statFileSafe(filePath) {
+  try {
+    const stat3 = await fs__namespace.stat(filePath);
+    return stat3.size;
+  } catch {
+    return 0;
+  }
+}
+function sumArray(arr) {
+  let total = 0;
+  for (let i = 0; i < arr.length; i++) {
+    total += arr[i] ?? 0;
+  }
+  return total;
+}
+async function removeDirSafe(dirPath) {
+  try {
+    await fs__namespace.rm(dirPath, { recursive: true, force: true });
+  } catch {
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
 
 // src/pacs/types.ts
 var QueryLevel = {
@@ -35060,11 +36098,11 @@ function addFilterKeys(keys, filter) {
   for (let i = 0; i < fields.length; i += 1) {
     const field = fields[i];
     if (field === void 0) continue;
-    const tag = FILTER_TAG_MAP[field];
-    if (tag === void 0) continue;
+    const tag2 = FILTER_TAG_MAP[field];
+    if (tag2 === void 0) continue;
     const value = filter[field];
     if (typeof value !== "string") continue;
-    keys.push(`${tag}=${value}`);
+    keys.push(`${tag2}=${value}`);
   }
 }
 function extractTag(key) {
@@ -35073,11 +36111,11 @@ function extractTag(key) {
 }
 function addReturnKeys(keys, returnKeys) {
   for (let i = 0; i < returnKeys.length; i += 1) {
-    const tag = returnKeys[i];
-    if (tag === void 0) continue;
-    const alreadyPresent = keys.some((k) => extractTag(k) === tag);
+    const tag2 = returnKeys[i];
+    if (tag2 === void 0) continue;
+    const alreadyPresent = keys.some((k) => extractTag(k) === tag2);
     if (!alreadyPresent) {
-      keys.push(`${tag}=`);
+      keys.push(`${tag2}=`);
     }
   }
 }
@@ -35105,13 +36143,13 @@ function buildWorklistKeys(filter) {
 var MAX_RESPONSE_FILES = 1e4;
 async function createTempDir() {
   return stderrLib.tryCatch(
-    () => promises.mkdtemp(path.join(os.tmpdir(), "dcmtk-pacs-")),
+    () => fs.mkdtemp(path.join(os.tmpdir(), "dcmtk-pacs-")),
     (e) => new Error(`Failed to create temp directory: ${e.message}`)
   );
 }
 async function listDcmFiles(directory) {
   try {
-    const entries = await promises.readdir(directory);
+    const entries = await fs.readdir(directory);
     const dcmFiles = [];
     for (let i = 0; i < entries.length; i += 1) {
       const entry = entries[i];
@@ -35129,7 +36167,7 @@ async function listDcmFiles(directory) {
 }
 async function cleanupTempDir(directory) {
   try {
-    await promises.rm(directory, { recursive: true, force: true });
+    await fs.rm(directory, { recursive: true, force: true });
   } catch {
   }
 }
@@ -35588,6 +36626,7 @@ async function retry(operation, options) {
 }
 
 exports.AETitleSchema = AETitleSchema;
+exports.AssociationTracker = AssociationTracker;
 exports.ChangeSet = ChangeSet;
 exports.ColorConversion = ColorConversion;
 exports.DCMPRSCP_FATAL_EVENTS = DCMPRSCP_FATAL_EVENTS;
@@ -35618,7 +36657,8 @@ exports.Dcmrecv = Dcmrecv;
 exports.DcmrecvEvent = DcmrecvEvent;
 exports.DcmtkProcess = DcmtkProcess;
 exports.DicomDataset = DicomDataset;
-exports.DicomFile = DicomFile;
+exports.DicomInstance = DicomInstance;
+exports.DicomReceiver = DicomReceiver;
 exports.DicomTagPathSchema = DicomTagPathSchema;
 exports.DicomTagSchema = DicomTagSchema;
 exports.FilenameMode = FilenameMode;
@@ -35637,6 +36677,7 @@ exports.PacsClient = PacsClient;
 exports.PortSchema = PortSchema;
 exports.PreferredTransferSyntax = PreferredTransferSyntax;
 exports.ProcessState = ProcessState;
+exports.ProposedTransferSyntax = ProposedTransferSyntax;
 exports.QueryLevel = QueryLevel;
 exports.QueryModel = QueryModel;
 exports.REQUIRED_BINARIES = REQUIRED_BINARIES;
@@ -35742,9 +36783,9 @@ exports.sopClassNameFromUID = sopClassNameFromUID;
 exports.spawnCommand = spawnCommand;
 exports.stl2dcm = stl2dcm;
 exports.storescu = storescu;
+exports.tag = tag;
 exports.tagPathToSegments = tagPathToSegments;
 exports.termscu = termscu;
-exports.unwrap = unwrap;
 exports.xml2dcm = xml2dcm;
 exports.xml2dsr = xml2dsr;
 exports.xmlToJson = xmlToJson;