dicom-synth 1.11.0 → 1.13.0

package/bin/dicom-synth-describe.mjs

@@ -6,12 +6,14 @@ import { describeDirectory } from '../dist/esm/index.js'
 
 function usage() {
   console.error(
-    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--gzip]\n' +
+    'Usage: dicom-synth-describe <dir> [--out <spec.json[.gz]>] [--keep-tags <a,b,...>] [--keep-tags-file <path>] [--size-tolerance <fraction>] [--no-preserve-uids] [--uid-salt <hex>] [--gzip]\n' +
       '\n' +
       'Scans a DICOM tree and emits a DatasetSpec describing its shape\n' +
       '(studies/series, per-file size, modality).\n' +
       '\n' +
-      'By default only the shape is reproduced — no tags are copied.\n' +
+      'UIDs are preserved by default as hash-derived synthetic UIDs, keeping\n' +
+      'cross-file links (FrameOfReferenceUID etc.) without emitting any original\n' +
+      'UID. Other tags are not copied unless named.\n' +
       '--keep-tags copies the named tags (DICOM keywords or 8-hex tags)\n' +
       "verbatim; if a kept tag holds PHI, handling it is the caller's\n" +
       "responsibility, not this tool's.\n" +
@@ -19,6 +21,11 @@ function usage() {
       'line, # comments); merged with any --keep-tags.\n' +
       '--size-tolerance folds near-identical file sizes (fraction, e.g. 0.05\n' +
       '= ±5%) into one entry; default exact.\n' +
+      '--no-preserve-uids emits shape only with freshly minted UIDs (no link\n' +
+      'preservation).\n' +
+      '--uid-salt fixes the hashing salt (hex) for a specific namespace; when\n' +
+      "omitted the salt derives from the dataset's own study UIDs (reproducible,\n" +
+      'and disjoint across datasets). The salt is reported on stderr.\n' +
       '--gzip (or a .gz --out suffix) writes the spec gzip-compressed.',
   )
   process.exit(1)
@@ -38,6 +45,8 @@ if (args.length === 0) usage()
 let dir
 let outPath
 let sizeTolerance
+let preserveUids = true
+let uidSalt
 let gzip = false
 const keepTags = []
 
@@ -64,6 +73,10 @@ for (let i = 0; i < args.length; i++) {
       console.error('--size-tolerance must be a non-negative number')
       process.exit(1)
     }
+  } else if (args[i] === '--no-preserve-uids') {
+    preserveUids = false
+  } else if (args[i] === '--uid-salt' && args[i + 1]) {
+    uidSalt = args[++i]
   } else if (args[i] === '--gzip') {
     gzip = true
   } else if (args[i].startsWith('--')) {
@@ -79,11 +92,18 @@ for (let i = 0; i < args.length; i++) {
 
 if (dir === undefined) usage()
 
+if (uidSalt !== undefined && !preserveUids) {
+  console.error('--uid-salt cannot be combined with --no-preserve-uids')
+  process.exit(1)
+}
+
 let result
 try {
   result = describeDirectory(dir, {
     ...(keepTags.length ? { keepTags } : {}),
     ...(sizeTolerance !== undefined ? { sizeTolerance } : {}),
+    preserveUids,
+    ...(uidSalt !== undefined ? { uidSalt } : {}),
   })
 } catch (err) {
   console.error(`Error: ${err.message}`)
@@ -103,6 +123,11 @@ const { dicomFiles, skipped, unknownModality } = result.stats
 console.error(
   `Described ${dicomFiles} DICOM file(s); skipped ${skipped} non-DICOM/ungroupable file(s)`,
 )
+if (result.spec.uidSalt) {
+  console.error(
+    `  UIDs hash-derived with salt ${result.spec.uidSalt} (reuse via --uid-salt to reproduce)`,
+  )
+}
 if (unknownModality > 0) {
   console.error(
     `  ${unknownModality} file(s) had an unsupported Modality — emitted as default (CT)`,

package/dist/esm/collection/writer.js

@@ -269,68 +269,37 @@ import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs
 import { resolve as resolve2 } from "node:path";
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
-function lcg(seed) {
-  let s = seed >>> 0;
-  return () => {
-    s = Math.imul(1664525, s) + 1013904223 >>> 0;
-    return s;
-  };
-}
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
 }
-var GROUP_STREAM_OFFSET = 2654435769;
-function seededStream(seed, offset, a, b) {
-  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
-}
-function makeGroupUidGenerator(seed) {
-  if (seed === void 0) {
-    return {
-      study: () => randomUid("study"),
-      series: () => randomUid("series")
-    };
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
   }
   return {
-    study: (studyIndex) => seededUid(
-      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
-      "study"
-    ),
-    series: (studyIndex, seriesIndex) => seededUid(
-      seededStream(
-        seed,
-        GROUP_STREAM_OFFSET,
-        studyIndex + 1,
-        seriesIndex + 1
-      ),
-      "series"
-    )
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
   };
 }
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 
 // src/syntheticFixtures/streamWrite.ts
@@ -443,7 +412,7 @@ function streamLargeImage(outPath, options) {
     fragmentBytes = FRAGMENT_MAX_BYTES
   } = options;
   const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
   const identity = { modality, uid, tags: options.tags };
   mkdirSync2(resolve2(outPath, ".."), { recursive: true });
   const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
@@ -622,13 +591,16 @@ function* seriesFiles(series) {
     }
   }
 }
-function resolveUid(seed, index, override) {
-  return { ...makeUidGenerator(seed)(index), ...override };
+function resolveUid(salt, index, override) {
+  return { ...makeUidGenerator(salt)(index), ...override };
+}
+function effectiveSalt(spec) {
+  return spec.uidSalt ?? seedToSalt(spec.seed);
 }
 async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
-  const uid = resolveUid(options?.seed, index, options?.uid);
+  const uid = resolveUid(effectiveSalt(options ?? {}), index, options?.uid);
   const resolvedSpec = "tags" in spec && spec.tags ? {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
@@ -700,6 +672,9 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
 function withResolvedSeed(spec) {
   return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
 }
+function withResolvedSalt(spec) {
+  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomBytes2(16).toString("hex") } : spec;
+}
 function computeNames(type, index, padWidth, grouped, quirks) {
   let names;
   if (grouped) {
@@ -740,7 +715,7 @@ function* planCollection(spec) {
       globalIndex++;
     }
   }
-  const groupUids = makeGroupUidGenerator(spec.seed);
+  const groupUids = makeGroupUidGenerator(effectiveSalt(spec));
   let studyOrdinal = 0;
   for (const study of studies) {
     const copies = study.count ?? 1;
@@ -782,21 +757,23 @@ function* planCollection(spec) {
     }
   }
 }
-async function materialisePlan(plan, seed) {
+async function materialisePlan(plan, salt) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
-    seed,
+    uidSalt: salt,
     uid: plan.uidOverride,
     context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
 async function* generateCollectionFromSpec(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
-    yield await materialisePlan(plan, spec.seed);
+    yield await materialisePlan(plan, salt);
   }
 }
 async function* previewCollection(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
     if (plan.fileSpec.type === "large-image") {
       yield {
@@ -806,7 +783,7 @@ async function* previewCollection(spec) {
         approxBytes: plan.fileSpec.targetBytes
       };
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       yield {
         relativePath: plan.relativePath,
         type: plan.fileSpec.type,
@@ -820,6 +797,7 @@ async function writeCollectionFromSpec(spec, outDir) {
   const root = resolve3(outDir);
   mkdirSync3(root, { recursive: true });
   const manifest = [];
+  const salt = effectiveSalt(spec);
   const createdDirs = /* @__PURE__ */ new Set([root]);
   const ensureDir = (filePath) => {
     const dir = dirname(filePath);
@@ -838,7 +816,7 @@ async function writeCollectionFromSpec(spec, outDir) {
           `large-image targetBytes (${large.targetBytes}) exceeds the 50 GB limit`
         );
       }
-      const uid = resolveUid(spec.seed, plan.index, plan.uidOverride);
+      const uid = resolveUid(salt, plan.index, plan.uidOverride);
       streamLargeImage(filePath, {
         targetBytes: large.targetBytes,
         modality: large.modality,
@@ -846,7 +824,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       await writeFile(filePath, file.buffer);
     }
     manifest.push({
@@ -861,6 +839,7 @@ export {
   generateCollectionFromSpec,
   generateFile,
   previewCollection,
+  withResolvedSalt,
   withResolvedSeed,
   writeCollectionFromSpec
 };

package/dist/esm/describe/describe.js

@@ -1,4 +1,5 @@
 // src/describe/describe.ts
+import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync,
   openSync,
@@ -105,6 +106,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -406,6 +414,7 @@ function validateDatasetSpec(raw) {
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
@@ -421,11 +430,20 @@ function validateDatasetSpec(raw) {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
 }
 
+// src/syntheticFixtures/uid.ts
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+
 // src/describe/describe.ts
 var dcmjsAny = dcmjs;
 var HEX_TAG_RE2 = /^[0-9a-fA-F]{8}$/;
@@ -583,6 +601,53 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+var DICOM_ORG_ROOT = "1.2.840.10008.";
+var UID_SWEEP_EXCLUDE = /* @__PURE__ */ new Set([
+  "StudyInstanceUID",
+  "SeriesInstanceUID",
+  "SOPClassUID"
+]);
+function vrOf(keyword) {
+  const nm = dcmjsAny.data.DicomMetaDictionary.nameMap;
+  return (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+}
+function hashUidVia(map, salt, original) {
+  let synthetic = map.get(original);
+  if (synthetic === void 0) {
+    synthetic = hashUid(salt, original);
+    map.set(original, synthetic);
+  }
+  return synthetic;
+}
+function collectUidOriginals(record) {
+  const uids = {};
+  let found = false;
+  for (const [keyword, value] of Object.entries(record)) {
+    if (UID_SWEEP_EXCLUDE.has(keyword)) continue;
+    if (typeof value !== "string" || value.startsWith(DICOM_ORG_ROOT)) continue;
+    if (vrOf(keyword) !== "UI") continue;
+    uids[keyword] = value;
+    found = true;
+  }
+  return found ? uids : void 0;
+}
+function hashUidTags(uids, salt, map) {
+  const tags = {};
+  for (const [keyword, original] of Object.entries(uids)) {
+    tags[keyword] = hashUidVia(map, salt, original);
+  }
+  return tags;
+}
+function deriveSalt(studyUids) {
+  const h = createHash2("sha256");
+  for (const uid of [...studyUids].sort()) h.update(uid).update("\n");
+  return h.digest("hex");
+}
+function mergeTags(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
 function sizeKbOf(bytes) {
   return Math.max(1, Math.round(bytes / 1024));
 }
@@ -687,7 +752,9 @@ function seriesSpecFromAccum(accum) {
 }
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
-  const keepTags = keepKeywords.length > 0;
+  const preserveUids = options.preserveUids ?? true;
+  const uidMap = /* @__PURE__ */ new Map();
+  const useRecords = keepKeywords.length > 0 || preserveUids;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -725,9 +792,16 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    const keptTags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    const uidOriginals = preserveUids ? collectUidOriginals(record) : void 0;
     const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
-    const fileRecord = { large, bytes, modality, tags };
+    const fileRecord = {
+      large,
+      bytes,
+      modality,
+      tags: keptTags,
+      uidOriginals
+    };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -735,7 +809,7 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = keepTags ? [] : /* @__PURE__ */ new Map();
+      series = useRecords ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
     if (Array.isArray(series)) {
@@ -744,13 +818,45 @@ function describeDirectory(dir, options = {}) {
       accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => ({
-    series: [...study.values()].map(seriesSpecFromAccum)
-  }));
+  const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
+  if (salt !== void 0) {
+    for (const study of studies.values()) {
+      for (const series of study.values()) {
+        if (!Array.isArray(series)) continue;
+        for (const rec of series) {
+          if (rec.uidOriginals) {
+            rec.tags = mergeTags(
+              rec.tags,
+              hashUidTags(rec.uidOriginals, salt, uidMap)
+            );
+          }
+        }
+      }
+    }
+  }
+  const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
+    ...spec2,
+    tags: {
+      ...spec2.tags,
+      SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
+    }
+  };
+  const studySpecs = [...studies.entries()].map(
+    ([studyUid, study]) => ({
+      ...salt !== void 0 ? { tags: { StudyInstanceUID: hashUidVia(uidMap, salt, studyUid) } } : {},
+      series: [...study.entries()].map(
+        ([seriesUid, accum]) => withGroupUid(seriesSpecFromAccum(accum), seriesUid)
+      )
+    })
+  );
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }
-  const spec = { studies: studySpecs, layout: "hierarchical" };
+  const spec = {
+    studies: studySpecs,
+    layout: "hierarchical",
+    ...salt !== void 0 ? { uidSalt: salt } : {}
+  };
   validateDatasetSpec(spec);
   return { spec, stats };
 }

package/dist/esm/index.js

@@ -154,6 +154,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -455,6 +462,7 @@ function validateDatasetSpec(raw) {
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
@@ -470,6 +478,7 @@ function validateDatasetSpec(raw) {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
@@ -585,6 +594,7 @@ function validateParametricSpec(raw) {
     }
   }
   if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "ParametricSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
   }
@@ -592,6 +602,7 @@ function validateParametricSpec(raw) {
     studies,
     ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }
@@ -779,8 +790,19 @@ import { closeSync, mkdirSync as mkdirSync2, openSync, writeSync } from "node:fs
 import { resolve as resolve2 } from "node:path";
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
+}
 function lcg(seed) {
   let s = seed >>> 0;
   return () => {
@@ -788,60 +810,28 @@ function lcg(seed) {
     return s;
   };
 }
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
-}
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
-}
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
-}
-var GROUP_STREAM_OFFSET = 2654435769;
 var PARAMETRIC_STREAM_OFFSET = 2246822507;
 function seededStream(seed, offset, a, b) {
   return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
 }
-function makeGroupUidGenerator(seed) {
-  if (seed === void 0) {
-    return {
-      study: () => randomUid("study"),
-      series: () => randomUid("series")
-    };
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
   }
   return {
-    study: (studyIndex) => seededUid(
-      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
-      "study"
-    ),
-    series: (studyIndex, seriesIndex) => seededUid(
-      seededStream(
-        seed,
-        GROUP_STREAM_OFFSET,
-        studyIndex + 1,
-        seriesIndex + 1
-      ),
-      "series"
-    )
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
   };
 }
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 
 // src/syntheticFixtures/streamWrite.ts
@@ -954,7 +944,7 @@ function streamLargeImage(outPath, options) {
     fragmentBytes = FRAGMENT_MAX_BYTES
   } = options;
   const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
   const identity = { modality, uid, tags: options.tags };
   mkdirSync2(resolve2(outPath, ".."), { recursive: true });
   const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
@@ -1006,6 +996,7 @@ function writeLargeImageFile(spec, outPath, options = {}) {
   return streamLargeImage(outPath, {
     targetBytes,
     modality: spec.modality,
+    uidSalt: spec.uidSalt,
     seed: spec.seed,
     chunkBytes: options.chunkBytes
   });
@@ -1153,13 +1144,16 @@ function* seriesFiles(series) {
     }
   }
 }
-function resolveUid(seed, index, override) {
-  return { ...makeUidGenerator(seed)(index), ...override };
+function resolveUid(salt, index, override) {
+  return { ...makeUidGenerator(salt)(index), ...override };
+}
+function effectiveSalt(spec) {
+  return spec.uidSalt ?? seedToSalt(spec.seed);
 }
 async function generateFile(spec, options) {
   const index = options?.index ?? 0;
   const padWidth = options?.padWidth ?? 3;
-  const uid = resolveUid(options?.seed, index, options?.uid);
+  const uid = resolveUid(effectiveSalt(options ?? {}), index, options?.uid);
   const resolvedSpec = "tags" in spec && spec.tags ? {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
@@ -1231,6 +1225,9 @@ function hierarchicalName(studyOrdinal, seriesIndex, instanceNumber) {
 function withResolvedSeed(spec) {
   return spec.seed === void 0 ? { ...spec, seed: randomBytes2(4).readUInt32BE(0) } : spec;
 }
+function withResolvedSalt(spec) {
+  return spec.uidSalt === void 0 ? { ...spec, uidSalt: randomBytes2(16).toString("hex") } : spec;
+}
 function computeNames(type, index, padWidth, grouped, quirks) {
   let names;
   if (grouped) {
@@ -1271,7 +1268,7 @@ function* planCollection(spec) {
       globalIndex++;
     }
   }
-  const groupUids = makeGroupUidGenerator(spec.seed);
+  const groupUids = makeGroupUidGenerator(effectiveSalt(spec));
   let studyOrdinal = 0;
   for (const study of studies) {
     const copies = study.count ?? 1;
@@ -1313,21 +1310,23 @@ function* planCollection(spec) {
     }
   }
 }
-async function materialisePlan(plan, seed) {
+async function materialisePlan(plan, salt) {
   const file = await generateFile(plan.fileSpec, {
     index: plan.index,
-    seed,
+    uidSalt: salt,
     uid: plan.uidOverride,
     context: plan.context
   });
   return { ...file, filename: plan.filename, relativePath: plan.relativePath };
 }
 async function* generateCollectionFromSpec(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
-    yield await materialisePlan(plan, spec.seed);
+    yield await materialisePlan(plan, salt);
   }
 }
 async function* previewCollection(spec) {
+  const salt = effectiveSalt(spec);
   for (const plan of planCollection(spec)) {
     if (plan.fileSpec.type === "large-image") {
       yield {
@@ -1337,7 +1336,7 @@ async function* previewCollection(spec) {
         approxBytes: plan.fileSpec.targetBytes
       };
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       yield {
         relativePath: plan.relativePath,
         type: plan.fileSpec.type,
@@ -1351,6 +1350,7 @@ async function writeCollectionFromSpec(spec, outDir) {
   const root = resolve3(outDir);
   mkdirSync3(root, { recursive: true });
   const manifest = [];
+  const salt = effectiveSalt(spec);
   const createdDirs = /* @__PURE__ */ new Set([root]);
   const ensureDir = (filePath) => {
     const dir = dirname(filePath);
@@ -1369,7 +1369,7 @@ async function writeCollectionFromSpec(spec, outDir) {
           `large-image targetBytes (${large.targetBytes}) exceeds the 50 GB limit`
         );
       }
-      const uid = resolveUid(spec.seed, plan.index, plan.uidOverride);
+      const uid = resolveUid(salt, plan.index, plan.uidOverride);
       streamLargeImage(filePath, {
         targetBytes: large.targetBytes,
         modality: large.modality,
@@ -1377,7 +1377,7 @@ async function writeCollectionFromSpec(spec, outDir) {
         tags: resolveTagTemplates(large.tags, plan.context)
       });
     } else {
-      const file = await materialisePlan(plan, spec.seed);
+      const file = await materialisePlan(plan, salt);
       await writeFile(filePath, file.buffer);
     }
     manifest.push({
@@ -1390,6 +1390,7 @@ async function writeCollectionFromSpec(spec, outDir) {
 }
 
 // src/describe/describe.ts
+import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync as closeSync2,
   openSync as openSync2,
@@ -1555,6 +1556,53 @@ function extractTags(record, keepKeywords) {
   }
   return found ? tags : void 0;
 }
+var DICOM_ORG_ROOT = "1.2.840.10008.";
+var UID_SWEEP_EXCLUDE = /* @__PURE__ */ new Set([
+  "StudyInstanceUID",
+  "SeriesInstanceUID",
+  "SOPClassUID"
+]);
+function vrOf(keyword) {
+  const nm = dcmjsAny2.data.DicomMetaDictionary.nameMap;
+  return (nm?.[keyword] ?? nm?.[`RETIRED_${keyword}`])?.vr;
+}
+function hashUidVia(map, salt, original) {
+  let synthetic = map.get(original);
+  if (synthetic === void 0) {
+    synthetic = hashUid(salt, original);
+    map.set(original, synthetic);
+  }
+  return synthetic;
+}
+function collectUidOriginals(record) {
+  const uids = {};
+  let found = false;
+  for (const [keyword, value] of Object.entries(record)) {
+    if (UID_SWEEP_EXCLUDE.has(keyword)) continue;
+    if (typeof value !== "string" || value.startsWith(DICOM_ORG_ROOT)) continue;
+    if (vrOf(keyword) !== "UI") continue;
+    uids[keyword] = value;
+    found = true;
+  }
+  return found ? uids : void 0;
+}
+function hashUidTags(uids, salt, map) {
+  const tags = {};
+  for (const [keyword, original] of Object.entries(uids)) {
+    tags[keyword] = hashUidVia(map, salt, original);
+  }
+  return tags;
+}
+function deriveSalt(studyUids) {
+  const h = createHash2("sha256");
+  for (const uid of [...studyUids].sort()) h.update(uid).update("\n");
+  return h.digest("hex");
+}
+function mergeTags(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  return { ...a, ...b };
+}
 function sizeKbOf(bytes) {
   return Math.max(1, Math.round(bytes / 1024));
 }
@@ -1659,7 +1707,9 @@ function seriesSpecFromAccum(accum) {
 }
 function describeDirectory(dir, options = {}) {
   const keepKeywords = options.keepTags ? resolveKeepTags(options.keepTags) : [];
-  const keepTags = keepKeywords.length > 0;
+  const preserveUids = options.preserveUids ?? true;
+  const uidMap = /* @__PURE__ */ new Map();
+  const useRecords = keepKeywords.length > 0 || preserveUids;
   const tolerance = options.sizeTolerance ?? 0;
   if (!Number.isFinite(tolerance) || tolerance < 0) {
     throw new Error(
@@ -1697,9 +1747,16 @@ function describeDirectory(dir, options = {}) {
         stats.unknownModality++;
       }
     }
-    const tags = keepTags ? extractTags(record, keepKeywords) : void 0;
+    const keptTags = keepKeywords.length ? extractTags(record, keepKeywords) : void 0;
+    const uidOriginals = preserveUids ? collectUidOriginals(record) : void 0;
     const bytes = large ? size : Math.min(bucketBytes(size, tolerance), MAX_PIXEL_BYTES);
-    const fileRecord = { large, bytes, modality, tags };
+    const fileRecord = {
+      large,
+      bytes,
+      modality,
+      tags: keptTags,
+      uidOriginals
+    };
     let study = studies.get(studyUid);
     if (!study) {
       study = /* @__PURE__ */ new Map();
@@ -1707,7 +1764,7 @@ function describeDirectory(dir, options = {}) {
     }
     let series = study.get(seriesUid);
     if (!series) {
-      series = keepTags ? [] : /* @__PURE__ */ new Map();
+      series = useRecords ? [] : /* @__PURE__ */ new Map();
       study.set(seriesUid, series);
     }
     if (Array.isArray(series)) {
@@ -1716,13 +1773,45 @@ function describeDirectory(dir, options = {}) {
       accumulate(series, fileRecord);
     }
   }
-  const studySpecs = [...studies.values()].map((study) => ({
-    series: [...study.values()].map(seriesSpecFromAccum)
-  }));
+  const salt = preserveUids ? options.uidSalt ?? deriveSalt([...studies.keys()]) : void 0;
+  if (salt !== void 0) {
+    for (const study of studies.values()) {
+      for (const series of study.values()) {
+        if (!Array.isArray(series)) continue;
+        for (const rec of series) {
+          if (rec.uidOriginals) {
+            rec.tags = mergeTags(
+              rec.tags,
+              hashUidTags(rec.uidOriginals, salt, uidMap)
+            );
+          }
+        }
+      }
+    }
+  }
+  const withGroupUid = (spec2, seriesUid) => salt === void 0 ? spec2 : {
+    ...spec2,
+    tags: {
+      ...spec2.tags,
+      SeriesInstanceUID: hashUidVia(uidMap, salt, seriesUid)
+    }
+  };
+  const studySpecs = [...studies.entries()].map(
+    ([studyUid, study]) => ({
+      ...salt !== void 0 ? { tags: { StudyInstanceUID: hashUidVia(uidMap, salt, studyUid) } } : {},
+      series: [...study.entries()].map(
+        ([seriesUid, accum]) => withGroupUid(seriesSpecFromAccum(accum), seriesUid)
+      )
+    })
+  );
   if (studySpecs.length === 0) {
     throw new Error(`describe: no DICOM series found in ${dir}`);
   }
-  const spec = { studies: studySpecs, layout: "hierarchical" };
+  const spec = {
+    studies: studySpecs,
+    layout: "hierarchical",
+    ...salt !== void 0 ? { uidSalt: salt } : {}
+  };
   validateDatasetSpec(spec);
   return { spec, stats };
 }
@@ -1759,7 +1848,7 @@ function loadCaseById(casesJsonPath, id) {
 }
 
 // src/public-fixtures/fetch.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash3 } from "node:crypto";
 import { existsSync, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
 import { join as join3 } from "node:path";
@@ -1768,7 +1857,7 @@ function caseCachePath(sha256, root = DEFAULT_CACHE_ROOT) {
   return join3(root, sha256, "file.dcm");
 }
 function verifySha256(buffer, expected) {
-  const h = createHash("sha256").update(buffer).digest("hex");
+  const h = createHash3("sha256").update(buffer).digest("hex");
   if (h !== expected) {
     throw new Error(
       `SHA256 mismatch: expected ${expected}, got ${h}. Upstream may have changed; bump metadata after review.`
@@ -1900,6 +1989,9 @@ function resolveParametricSpec(spec) {
     ...entries.length > 0 ? { entries } : {},
     studies,
     seed,
+    // Pass an explicit salt through; when absent, UIDs derive from `seed` so the
+    // resolved spec stays deterministic ("same seed → identical resolved spec").
+    ...validated.uidSalt !== void 0 ? { uidSalt: validated.uidSalt } : {},
     ...validated.layout !== void 0 ? { layout: validated.layout } : {}
   };
 }
@@ -1913,16 +2005,19 @@ export {
   fetchPublicCaseToCache,
   generateCollectionFromSpec,
   generateFile,
+  hashUid,
   loadCaseById,
   loadCasesFromJson,
   loadDefaultCases,
   previewCollection,
   resolveParametricSpec,
   resolveTagTemplates,
+  seedToSalt,
   streamLargeImage,
   validateDatasetSpec,
   validateParametricSpec,
   verifySha256,
+  withResolvedSalt,
   withResolvedSeed,
   writeCollectionFromSpec,
   writeLargeImageFile

package/dist/esm/schema/parametric.js

@@ -2,7 +2,7 @@
 import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 function lcg(seed) {
   let s = seed >>> 0;
   return () => {
@@ -90,6 +90,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -361,6 +368,7 @@ function validateParametricSpec(raw) {
     }
   }
   if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "ParametricSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
   }
@@ -368,6 +376,7 @@ function validateParametricSpec(raw) {
     studies,
     ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }
@@ -471,6 +480,9 @@ function resolveParametricSpec(spec) {
     ...entries.length > 0 ? { entries } : {},
     studies,
     seed,
+    // Pass an explicit salt through; when absent, UIDs derive from `seed` so the
+    // resolved spec stays deterministic ("same seed → identical resolved spec").
+    ...validated.uidSalt !== void 0 ? { uidSalt: validated.uidSalt } : {},
     ...validated.layout !== void 0 ? { layout: validated.layout } : {}
   };
 }

package/dist/esm/schema/validate.js

@@ -79,6 +79,13 @@ function validateSeed(value, path) {
     );
   }
 }
+function validateUidSalt(value, path) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `${path}: must be a non-empty string; got ${JSON.stringify(value)}`
+    );
+  }
+}
 function validateSizeKbLimit(kb, path) {
   if (kb * 1024 > MAX_PIXEL_BYTES) {
     throw new Error(`${path}: exceeds the 512 MB limit`);
@@ -380,6 +387,7 @@ function validateDatasetSpec(raw) {
     (study, i) => validateStudy(study, `studies[${i}]`)
   );
   if ("seed" in r) validateSeed(r.seed, "DatasetSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "DatasetSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "DatasetSpec.layout");
   }
@@ -395,6 +403,7 @@ function validateDatasetSpec(raw) {
     ...entries.length > 0 ? { entries } : {},
     ...studies.length > 0 ? { studies } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {},
     ...r.pathQuirks !== void 0 ? { pathQuirks: r.pathQuirks } : {}
   };
@@ -510,6 +519,7 @@ function validateParametricSpec(raw) {
     }
   }
   if ("seed" in r) validateSeed(r.seed, "ParametricSpec.seed");
+  if ("uidSalt" in r) validateUidSalt(r.uidSalt, "ParametricSpec.uidSalt");
   if ("layout" in r) {
     validateEnum(r.layout, VALID_LAYOUTS, "ParametricSpec.layout");
   }
@@ -517,6 +527,7 @@ function validateParametricSpec(raw) {
     studies,
     ...edgeCases.length > 0 ? { edgeCases } : {},
     ...r.seed !== void 0 ? { seed: r.seed } : {},
+    ...r.uidSalt !== void 0 ? { uidSalt: r.uidSalt } : {},
     ...r.layout !== void 0 ? { layout: r.layout } : {}
   };
 }

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -144,44 +144,28 @@ function serializeDict(meta, dataset) {
 }
 
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
-function lcg(seed) {
-  let s = seed >>> 0;
-  return () => {
-    s = Math.imul(1664525, s) + 1013904223 >>> 0;
-    return s;
-  };
-}
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
 }
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
 }
-function seededStream(seed, offset, a, b) {
-  return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
-}
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 
 // src/syntheticFixtures/streamWrite.ts
@@ -294,7 +278,7 @@ function streamLargeImage(outPath, options) {
     fragmentBytes = FRAGMENT_MAX_BYTES
   } = options;
   const modality = options.modality ?? "CT";
-  const uid = options.uid ?? makeUidGenerator(options.seed)(0);
+  const uid = options.uid ?? makeUidGenerator(options.uidSalt ?? seedToSalt(options.seed))(0);
   const identity = { modality, uid, tags: options.tags };
   mkdirSync2(resolve2(outPath, ".."), { recursive: true });
   const zeroChunk = Buffer.alloc(Math.max(1, chunkBytes));
@@ -346,6 +330,7 @@ function writeLargeImageFile(spec, outPath, options = {}) {
   return streamLargeImage(outPath, {
     targetBytes,
     modality: spec.modality,
+    uidSalt: spec.uidSalt,
     seed: spec.seed,
     chunkBytes: options.chunkBytes
   });

package/dist/esm/syntheticFixtures/uid.js

@@ -1,6 +1,17 @@
 // src/syntheticFixtures/uid.ts
-import { randomBytes } from "node:crypto";
-var ROLE_CODE = { study: 1, series: 2, sop: 3 };
+import { createHash, randomBytes } from "node:crypto";
+function hashUid(salt, key) {
+  const digest = createHash("sha256").update(salt).update(" ").update(key).digest();
+  const n = BigInt(`0x${digest.subarray(0, 16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function randomUid() {
+  const n = BigInt(`0x${randomBytes(16).toString("hex")}`);
+  return `2.25.${n.toString()}`;
+}
+function seedToSalt(seed) {
+  return seed === void 0 ? void 0 : `seed:${seed}`;
+}
 function lcg(seed) {
   let s = seed >>> 0;
   return () => {
@@ -8,64 +19,34 @@ function lcg(seed) {
     return s;
   };
 }
-function formatUid(a, b, role) {
-  return `2.25.${a}.${b}.${ROLE_CODE[role]}`;
-}
-function randomUid(role) {
-  const buf = randomBytes(8);
-  return formatUid(buf.readUInt32BE(0), buf.readUInt32BE(4), role);
-}
-function seededUid(next, role) {
-  return formatUid(next(), next(), role);
-}
-var GROUP_STREAM_OFFSET = 2654435769;
 var PARAMETRIC_STREAM_OFFSET = 2246822507;
 function seededStream(seed, offset, a, b) {
   return lcg(seed * 999983 + offset + a * 1000003 + b * 7919 >>> 0);
 }
-function makeGroupUidGenerator(seed) {
-  if (seed === void 0) {
-    return {
-      study: () => randomUid("study"),
-      series: () => randomUid("series")
-    };
+function makeGroupUidGenerator(salt) {
+  if (salt === void 0) {
+    return { study: () => randomUid(), series: () => randomUid() };
   }
   return {
-    study: (studyIndex) => seededUid(
-      seededStream(seed, GROUP_STREAM_OFFSET, studyIndex + 1, 0),
-      "study"
-    ),
-    series: (studyIndex, seriesIndex) => seededUid(
-      seededStream(
-        seed,
-        GROUP_STREAM_OFFSET,
-        studyIndex + 1,
-        seriesIndex + 1
-      ),
-      "series"
-    )
+    study: (studyIndex) => hashUid(salt, `study:${studyIndex}`),
+    series: (studyIndex, seriesIndex) => hashUid(salt, `series:${studyIndex}:${seriesIndex}`)
   };
 }
-function makeUidGenerator(seed) {
-  if (seed === void 0) {
-    return () => ({
-      study: randomUid("study"),
-      series: randomUid("series"),
-      sop: randomUid("sop")
-    });
+function makeUidGenerator(salt) {
+  if (salt === void 0) {
+    return () => ({ study: randomUid(), series: randomUid(), sop: randomUid() });
   }
-  return (fileIndex) => {
-    const next = seededStream(seed, 0, fileIndex, 0);
-    return {
-      study: seededUid(next, "study"),
-      series: seededUid(next, "series"),
-      sop: seededUid(next, "sop")
-    };
-  };
+  return (fileIndex) => ({
+    study: hashUid(salt, `study:flat:${fileIndex}`),
+    series: hashUid(salt, `series:flat:${fileIndex}`),
+    sop: hashUid(salt, `sop:${fileIndex}`)
+  });
 }
 export {
   PARAMETRIC_STREAM_OFFSET,
+  hashUid,
   makeGroupUidGenerator,
   makeUidGenerator,
+  seedToSalt,
   seededStream
 };

package/dist/types/collection/writer.d.ts

@@ -16,11 +16,13 @@ export type CollectionManifest = Array<{
 export declare function generateFile(spec: FileSpec, options?: {
     index?: number;
     seed?: number;
+    uidSalt?: string;
     padWidth?: number;
     uid?: Partial<UidSet>;
     context?: Partial<TagContext>;
 }): Promise<GeneratedFile>;
 export declare function withResolvedSeed(spec: DatasetSpec): DatasetSpec;
+export declare function withResolvedSalt(spec: DatasetSpec): DatasetSpec;
 export declare function generateCollectionFromSpec(spec: DatasetSpec): AsyncGenerator<GeneratedFile>;
 export type CollectionPreviewItem = {
     relativePath: string;

package/dist/types/describe/describe.d.ts

@@ -2,6 +2,8 @@ import type { DatasetSpec } from '../schema/types.js';
 export type DescribeOptions = {
     keepTags?: string[];
     sizeTolerance?: number;
+    preserveUids?: boolean;
+    uidSalt?: string;
 };
 export type DescribeResult = {
     spec: DatasetSpec;

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { type CollectionManifest, type CollectionPreviewItem, type GeneratedFile, generateCollectionFromSpec, generateFile, previewCollection, withResolvedSeed, writeCollectionFromSpec, } from './collection/writer.js';
+export { type CollectionManifest, type CollectionPreviewItem, type GeneratedFile, generateCollectionFromSpec, generateFile, previewCollection, withResolvedSalt, withResolvedSeed, writeCollectionFromSpec, } from './collection/writer.js';
 export { type DescribeOptions, type DescribeResult, describeDirectory, } from './describe/describe.js';
 export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCases, type PublicCaseRecord, type PublicCaseSource, } from './public-fixtures/catalog.js';
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
@@ -8,3 +8,4 @@ export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, FakeS
 export { validateDatasetSpec, validateParametricSpec, } from './schema/validate.js';
 export { type LargeFileEncoding, type LargeFileResult, type LargeImageSpec, type StreamLargeImageOptions, streamLargeImage, writeLargeImageFile, } from './syntheticFixtures/streamWrite.js';
 export { resolveTagTemplates, type TagContext, TEMPLATE_VOCAB, } from './syntheticFixtures/tagTemplate.js';
+export { hashUid, seedToSalt } from './syntheticFixtures/uid.js';

package/dist/types/schema/types.d.ts

@@ -74,6 +74,7 @@ export type DatasetSpec = {
     entries?: EntrySpec[];
     studies?: StudySpec[];
     seed?: number;
+    uidSalt?: string;
     layout?: DatasetLayout;
     pathQuirks?: PathQuirk[];
 };
@@ -96,6 +97,7 @@ export type ParametricEdgeCase = EntrySpec & {
 };
 export type ParametricSpec = {
     seed?: number;
+    uidSalt?: string;
     studies: ParametricStudies;
     edgeCases?: ParametricEdgeCase[];
     layout?: DatasetLayout;

package/dist/types/syntheticFixtures/streamWrite.d.ts

@@ -4,7 +4,9 @@ export type LargeImageSpec = {
     /** Approximate total file size in bytes (must exceed the 512 MB cap). */
     targetBytes: number;
     modality?: Modality;
-    /** Drawn when omitted; fixes the instance UIDs for reproducibility. */
+    /** UID namespace (hash-derived UIDs); random when both salt and seed omitted. */
+    uidSalt?: string;
+    /** Bridged to a salt when uidSalt is omitted; fixes the instance UIDs. */
     seed?: number;
 };
 export type LargeFileEncoding = 'native' | 'encapsulated';
@@ -18,7 +20,9 @@ export type StreamLargeImageOptions = {
     /** Approximate total file size in bytes (no floor — small values are valid). */
     targetBytes: number;
     modality?: Modality;
-    /** Drawn when omitted; fixes the instance UIDs for reproducibility. */
+    /** UID namespace (hash-derived UIDs); random when both salt and seed omitted. */
+    uidSalt?: string;
+    /** Bridged to a salt when uidSalt is omitted; fixes the instance UIDs. */
     seed?: number;
     /** Explicit UID set — used as-is (e.g. collection threading shared study/series UIDs). */
     uid?: UidSet;

package/dist/types/syntheticFixtures/uid.d.ts

@@ -3,12 +3,14 @@ export type UidSet = {
     series: string;
     sop: string;
 };
+export declare function hashUid(salt: string, key: string): string;
+export declare function seedToSalt(seed: number | undefined): string | undefined;
 export declare const PARAMETRIC_STREAM_OFFSET = 2246822507;
 export declare function seededStream(seed: number, offset: number, a: number, b: number): () => number;
 export type GroupUidGenerator = {
     study: (studyIndex: number) => string;
     series: (studyIndex: number, seriesIndex: number) => string;
 };
-export declare function makeGroupUidGenerator(seed?: number): GroupUidGenerator;
+export declare function makeGroupUidGenerator(salt?: string): GroupUidGenerator;
 export type UidGenerator = (fileIndex: number) => UidSet;
-export declare function makeUidGenerator(seed?: number): UidGenerator;
+export declare function makeUidGenerator(salt?: string): UidGenerator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",