@absolutejs/artifacts 0.2.0 → 0.3.0

package/dist/index.js

@@ -58,35 +58,635 @@ var defineArtifactRegistry = (definitions) => ({
 // src/generators.ts
 var createArtifactGeneratorRegistry = (initial = []) => {
   const generators = new Map(initial.map((generator) => [generator.kind, generator]));
+  const generateResult = async (input) => {
+    const generator = generators.get(input.kind);
+    if (!generator) {
+      throw new ArtifactError("generator_unavailable", `No generator is registered for ${input.kind} artifacts`);
+    }
+    const context = { ownerId: input.ownerId };
+    const result = await generator.generate(input, context);
+    const issues = await generator.validate?.(result, input, context) ?? [];
+    if (issues.length > 0) {
+      throw new ArtifactError("batch_validation_failed", issues.map((issue) => `${issue.code}: ${issue.message}`).join("; "));
+    }
+    return result;
+  };
+  const bundleInput = (input, result) => ({
+    assets: result.assets,
+    content: result.content,
+    createdBy: input.createdBy,
+    kind: input.kind,
+    metadata: {
+      ...result.metadata,
+      ...result.warnings?.length ? { generationWarnings: result.warnings } : {}
+    },
+    provenance: result.provenance,
+    title: result.title ?? input.title ?? `Generated ${input.kind}`
+  });
   return {
     generate: async (service, input) => {
-      const generator = generators.get(input.kind);
-      if (!generator) {
-        throw new ArtifactError("generator_unavailable", `No generator is registered for ${input.kind} artifacts`);
-      }
-      const result = await generator.generate(input, {
-        ownerId: input.ownerId
-      });
-      const artifact = await service.createBundle(input.ownerId, {
-        assets: result.assets,
-        content: result.content,
-        createdBy: input.createdBy,
-        kind: input.kind,
-        metadata: {
-          ...result.metadata,
-          ...result.warnings?.length ? { generationWarnings: result.warnings } : {}
-        },
-        provenance: result.provenance,
-        title: result.title ?? input.title ?? `Generated ${input.kind}`
-      });
+      const result = await generateResult(input);
+      const artifact = await service.createBundle(input.ownerId, bundleInput(input, result));
       return artifact;
     },
+    generateBatch: async (service, input) => {
+      const generated = await Promise.all(input.items.map(async (item) => {
+        const generationInput = {
+          createdBy: item.createdBy,
+          input: item.input,
+          kind: item.kind,
+          ownerId: input.ownerId,
+          prompt: item.prompt,
+          title: item.title
+        };
+        const generator = generators.get(item.kind);
+        if (!generator) {
+          throw new ArtifactError("generator_unavailable", `No generator is registered for ${item.kind} artifacts`);
+        }
+        const context = { ownerId: input.ownerId };
+        const result = await generator.generate(generationInput, context);
+        const issues = await generator.validate?.(result, generationInput, context) ?? [];
+        return {
+          artifact: bundleInput(generationInput, result),
+          evidence: item.evidence,
+          generationIssues: issues,
+          key: item.key
+        };
+      }));
+      const staged = await service.stageBatch(input.ownerId, {
+        bundleId: input.bundleId,
+        commitMode: input.commitMode,
+        evidence: input.evidence,
+        items: generated.map(({ generationIssues: _issues, ...item }) => item),
+        metadata: input.metadata,
+        provenance: input.provenance
+      }, {
+        validators: [
+          () => generated.flatMap((item) => item.generationIssues.map((generationIssue) => ({
+            ...generationIssue,
+            itemKey: item.key
+          }))),
+          ...input.validators ?? []
+        ]
+      });
+      return staged.commit();
+    },
     kinds: () => [...generators.keys()],
     register: (generator) => {
       generators.set(generator.kind, generator);
     }
   };
 };
+// node_modules/fflate/esm/index.mjs
+import { createRequire } from "module";
+var require2 = createRequire("/");
+var _a;
+var Worker;
+var isMarkedAsUntransferable;
+try {
+  _a = require2("worker_threads"), Worker = _a.Worker, isMarkedAsUntransferable = _a.isMarkedAsUntransferable;
+} catch (e) {}
+var u8 = Uint8Array;
+var u16 = Uint16Array;
+var i32 = Int32Array;
+var fleb = new u8([0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0, 0, 0, 0]);
+var fdeb = new u8([0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13, 0, 0]);
+var clim = new u8([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]);
+var freb = function(eb, start) {
+  var b = new u16(31);
+  for (var i = 0;i < 31; ++i) {
+    b[i] = start += 1 << eb[i - 1];
+  }
+  var r = new i32(b[30]);
+  for (var i = 1;i < 30; ++i) {
+    for (var j = b[i];j < b[i + 1]; ++j) {
+      r[j] = j - b[i] << 5 | i;
+    }
+  }
+  return { b, r };
+};
+var _a = freb(fleb, 2);
+var fl = _a.b;
+var revfl = _a.r;
+fl[28] = 258, revfl[258] = 28;
+var _b = freb(fdeb, 0);
+var fd = _b.b;
+var revfd = _b.r;
+var rev = new u16(32768);
+for (i = 0;i < 32768; ++i) {
+  x = (i & 43690) >> 1 | (i & 21845) << 1;
+  x = (x & 52428) >> 2 | (x & 13107) << 2;
+  x = (x & 61680) >> 4 | (x & 3855) << 4;
+  rev[i] = ((x & 65280) >> 8 | (x & 255) << 8) >> 1;
+}
+var x;
+var i;
+var hMap = function(cd, mb, r) {
+  var s = cd.length;
+  var i2 = 0;
+  var l = new u16(mb);
+  for (;i2 < s; ++i2) {
+    if (cd[i2])
+      ++l[cd[i2] - 1];
+  }
+  var le = new u16(mb);
+  for (i2 = 1;i2 < mb; ++i2) {
+    le[i2] = le[i2 - 1] + l[i2 - 1] << 1;
+  }
+  var co;
+  if (r) {
+    co = new u16(1 << mb);
+    var rvb = 15 - mb;
+    for (i2 = 0;i2 < s; ++i2) {
+      if (cd[i2]) {
+        var sv = i2 << 4 | cd[i2];
+        var r_1 = mb - cd[i2];
+        var v = le[cd[i2] - 1]++ << r_1;
+        for (var m = v | (1 << r_1) - 1;v <= m; ++v) {
+          co[rev[v] >> rvb] = sv;
+        }
+      }
+    }
+  } else {
+    co = new u16(s);
+    for (i2 = 0;i2 < s; ++i2) {
+      if (cd[i2]) {
+        co[i2] = rev[le[cd[i2] - 1]++] >> 15 - cd[i2];
+      }
+    }
+  }
+  return co;
+};
+var flt = new u8(288);
+for (i = 0;i < 144; ++i)
+  flt[i] = 8;
+var i;
+for (i = 144;i < 256; ++i)
+  flt[i] = 9;
+var i;
+for (i = 256;i < 280; ++i)
+  flt[i] = 7;
+var i;
+for (i = 280;i < 288; ++i)
+  flt[i] = 8;
+var i;
+var fdt = new u8(32);
+for (i = 0;i < 32; ++i)
+  fdt[i] = 5;
+var i;
+var flrm = /* @__PURE__ */ hMap(flt, 9, 1);
+var fdrm = /* @__PURE__ */ hMap(fdt, 5, 1);
+var max = function(a) {
+  var m = a[0];
+  for (var i2 = 1;i2 < a.length; ++i2) {
+    if (a[i2] > m)
+      m = a[i2];
+  }
+  return m;
+};
+var bits = function(d, p, m) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8) >> (p & 7) & m;
+};
+var bits16 = function(d, p) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8 | d[o + 2] << 16) >> (p & 7);
+};
+var shft = function(p) {
+  return (p + 7) / 8 | 0;
+};
+var slc = function(v, s, e) {
+  if (s == null || s < 0)
+    s = 0;
+  if (e == null || e > v.length)
+    e = v.length;
+  return new u8(v.subarray(s, e));
+};
+var ec = [
+  "unexpected EOF",
+  "invalid block type",
+  "invalid length/literal",
+  "invalid distance",
+  "stream finished",
+  "no stream handler",
+  ,
+  "no callback",
+  "invalid UTF-8 data",
+  "extra field too long",
+  "date not in range 1980-2099",
+  "filename too long",
+  "stream finishing",
+  "invalid zip data"
+];
+var err = function(ind, msg, nt) {
+  var e = new Error(msg || ec[ind]);
+  e.code = ind;
+  if (Error.captureStackTrace)
+    Error.captureStackTrace(e, err);
+  if (!nt)
+    throw e;
+  return e;
+};
+var inflt = function(dat, st, buf, dict) {
+  var sl = dat.length, dl = dict ? dict.length : 0;
+  if (!sl || st.f && !st.l)
+    return buf || new u8(0);
+  var noBuf = !buf;
+  var resize = noBuf || st.i != 2;
+  var noSt = st.i;
+  if (noBuf)
+    buf = new u8(sl * 3);
+  var cbuf = function(l2) {
+    var bl = buf.length;
+    if (l2 > bl) {
+      var nbuf = new u8(Math.max(bl * 2, l2));
+      nbuf.set(buf);
+      buf = nbuf;
+    }
+  };
+  var final = st.f || 0, pos = st.p || 0, bt = st.b || 0, lm = st.l, dm = st.d, lbt = st.m, dbt = st.n;
+  var tbts = sl * 8;
+  do {
+    if (!lm) {
+      final = bits(dat, pos, 1);
+      var type = bits(dat, pos + 1, 3);
+      pos += 3;
+      if (!type) {
+        var s = shft(pos) + 4, l = dat[s - 4] | dat[s - 3] << 8, t = s + l;
+        if (t > sl) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + l);
+        buf.set(dat.subarray(s, t), bt);
+        st.b = bt += l, st.p = pos = t * 8, st.f = final;
+        continue;
+      } else if (type == 1)
+        lm = flrm, dm = fdrm, lbt = 9, dbt = 5;
+      else if (type == 2) {
+        var hLit = bits(dat, pos, 31) + 257, hcLen = bits(dat, pos + 10, 15) + 4;
+        var tl = hLit + bits(dat, pos + 5, 31) + 1;
+        pos += 14;
+        var ldt = new u8(tl);
+        var clt = new u8(19);
+        for (var i2 = 0;i2 < hcLen; ++i2) {
+          clt[clim[i2]] = bits(dat, pos + i2 * 3, 7);
+        }
+        pos += hcLen * 3;
+        var clb = max(clt), clbmsk = (1 << clb) - 1;
+        var clm = hMap(clt, clb, 1);
+        for (var i2 = 0;i2 < tl; ) {
+          var r = clm[bits(dat, pos, clbmsk)];
+          pos += r & 15;
+          var s = r >> 4;
+          if (s < 16) {
+            ldt[i2++] = s;
+          } else {
+            var c = 0, n = 0;
+            if (s == 16)
+              n = 3 + bits(dat, pos, 3), pos += 2, c = ldt[i2 - 1];
+            else if (s == 17)
+              n = 3 + bits(dat, pos, 7), pos += 3;
+            else if (s == 18)
+              n = 11 + bits(dat, pos, 127), pos += 7;
+            while (n--)
+              ldt[i2++] = c;
+          }
+        }
+        var lt = ldt.subarray(0, hLit), dt = ldt.subarray(hLit);
+        lbt = max(lt);
+        dbt = max(dt);
+        lm = hMap(lt, lbt, 1);
+        dm = hMap(dt, dbt, 1);
+      } else
+        err(1);
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+    }
+    if (resize)
+      cbuf(bt + 131072);
+    var lms = (1 << lbt) - 1, dms = (1 << dbt) - 1;
+    var lpos = pos;
+    for (;; lpos = pos) {
+      var c = lm[bits16(dat, pos) & lms], sym = c >> 4;
+      pos += c & 15;
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+      if (!c)
+        err(2);
+      if (sym < 256)
+        buf[bt++] = sym;
+      else if (sym == 256) {
+        lpos = pos, lm = null;
+        break;
+      } else {
+        var add = sym - 254;
+        if (sym > 264) {
+          var i2 = sym - 257, b = fleb[i2];
+          add = bits(dat, pos, (1 << b) - 1) + fl[i2];
+          pos += b;
+        }
+        var d = dm[bits16(dat, pos) & dms], dsym = d >> 4;
+        if (!d)
+          err(3);
+        pos += d & 15;
+        var dt = fd[dsym];
+        if (dsym > 3) {
+          var b = fdeb[dsym];
+          dt += bits16(dat, pos) & (1 << b) - 1, pos += b;
+        }
+        if (pos > tbts) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + 131072);
+        var end = bt + add;
+        if (bt < dt) {
+          var shift = dl - dt, dend = Math.min(dt, end);
+          if (shift + bt < 0)
+            err(3);
+          for (;bt < dend; ++bt)
+            buf[bt] = dict[shift + bt];
+        }
+        for (;bt < end; ++bt)
+          buf[bt] = buf[bt - dt];
+      }
+    }
+    st.l = lm, st.p = lpos, st.b = bt, st.f = final;
+    if (lm)
+      final = 1, st.m = lbt, st.d = dm, st.n = dbt;
+  } while (!final);
+  return bt != buf.length && noBuf ? slc(buf, 0, bt) : buf.subarray(0, bt);
+};
+var et = /* @__PURE__ */ new u8(0);
+var b2 = function(d, b) {
+  return d[b] | d[b + 1] << 8;
+};
+var b4 = function(d, b) {
+  return (d[b] | d[b + 1] << 8 | d[b + 2] << 16 | d[b + 3] << 24) >>> 0;
+};
+var b8 = function(d, b) {
+  return b4(d, b) + b4(d, b + 4) * 4294967296;
+};
+function inflateSync(data, opts) {
+  return inflt(data, { i: 2 }, opts && opts.out, opts && opts.dictionary);
+}
+var td = typeof TextDecoder != "undefined" && /* @__PURE__ */ new TextDecoder;
+var tds = 0;
+try {
+  td.decode(et, { stream: true });
+  tds = 1;
+} catch (e) {}
+var dutf8 = function(d) {
+  for (var r = "", i2 = 0;; ) {
+    var c = d[i2++];
+    var eb = (c > 127) + (c > 223) + (c > 239);
+    if (i2 + eb > d.length)
+      return { s: r, r: slc(d, i2 - 1) };
+    if (!eb)
+      r += String.fromCharCode(c);
+    else if (eb == 3) {
+      c = ((c & 15) << 18 | (d[i2++] & 63) << 12 | (d[i2++] & 63) << 6 | d[i2++] & 63) - 65536, r += String.fromCharCode(55296 | c >> 10, 56320 | c & 1023);
+    } else if (eb & 1)
+      r += String.fromCharCode((c & 31) << 6 | d[i2++] & 63);
+    else
+      r += String.fromCharCode((c & 15) << 12 | (d[i2++] & 63) << 6 | d[i2++] & 63);
+  }
+};
+function strFromU8(dat, latin1) {
+  if (latin1) {
+    var r = "";
+    for (var i2 = 0;i2 < dat.length; i2 += 16384)
+      r += String.fromCharCode.apply(null, dat.subarray(i2, i2 + 16384));
+    return r;
+  } else if (td) {
+    return td.decode(dat);
+  } else {
+    var _a2 = dutf8(dat), s = _a2.s, r = _a2.r;
+    if (r.length)
+      err(8);
+    return s;
+  }
+}
+var slzh = function(d, b) {
+  return b + 30 + b2(d, b + 26) + b2(d, b + 28);
+};
+var zh = function(d, b, z) {
+  var fnl = b2(d, b + 28), efl = b2(d, b + 30), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl;
+  var _a2 = z64hs(d, es, efl, z, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
+  return [b2(d, b + 10), sc, su, fn, es + efl + b2(d, b + 32), off];
+};
+var z64hs = function(d, b, l, z, sc, su, off) {
+  var nsc = sc == 4294967295, nsu = su == 4294967295, noff = off == 4294967295, e = b + l;
+  var nf = nsc + nsu + noff;
+  if (z && nf) {
+    for (;b + 4 < e; b += 4 + b2(d, b + 2)) {
+      if (b2(d, b) == 1) {
+        return [
+          nsc ? b8(d, b + 4 + 8 * nsu) : sc,
+          nsu ? b8(d, b + 4) : su,
+          noff ? b8(d, b + 4 + 8 * (nsu + nsc)) : off,
+          1
+        ];
+      }
+    }
+    if (z < 2)
+      err(13);
+  }
+  return [sc, su, off, 0];
+};
+function unzipSync(data, opts) {
+  var files = {};
+  var e = data.length - 22;
+  for (;b4(data, e) != 101010256; --e) {
+    if (!e || data.length - e > 65558)
+      err(13);
+  }
+  var c = b2(data, e + 8);
+  if (!c)
+    return {};
+  var o = b4(data, e + 16);
+  var z = b4(data, e - 20) == 117853008;
+  if (z) {
+    var ze = b4(data, e - 12);
+    z = b4(data, ze) == 101075792;
+    if (z) {
+      c = b4(data, ze + 32);
+      o = b4(data, ze + 48);
+    }
+  }
+  var fltr = opts && opts.filter;
+  for (var i2 = 0;i2 < c; ++i2) {
+    var _a2 = zh(data, o, z), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    o = no;
+    if (!fltr || fltr({
+      name: fn,
+      size: sc,
+      originalSize: su,
+      compression: c_2
+    })) {
+      if (!c_2)
+        files[fn] = slc(data, b, b + sc);
+      else if (c_2 == 8)
+        files[fn] = inflateSync(data.subarray(b, b + sc), { out: new u8(su) });
+      else
+        err(14, "unknown compression type " + c_2);
+    }
+  }
+  return files;
+}
+
+// src/validation.ts
+var decode = (data) => new TextDecoder().decode(data);
+var issue = (code, message, path) => ({
+  code,
+  message,
+  ...path ? { path } : {}
+});
+var parseCsvRows = (value) => {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let quoted = false;
+  for (let index = 0;index < value.length; index += 1) {
+    const character = value[index];
+    if (character === '"') {
+      if (quoted && value[index + 1] === '"') {
+        field += '"';
+        index += 1;
+      } else {
+        quoted = !quoted;
+      }
+    } else if (character === "," && !quoted) {
+      row.push(field);
+      field = "";
+    } else if ((character === `
+` || character === "\r") && !quoted) {
+      if (character === "\r" && value[index + 1] === `
+`)
+        index += 1;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else {
+      field += character;
+    }
+  }
+  if (quoted)
+    throw new Error("CSV contains an unterminated quoted field");
+  if (field.length > 0 || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows.filter((candidate) => candidate.some((cell) => cell.length > 0));
+};
+var validateCsv = (data, path) => {
+  const rows = parseCsvRows(decode(data));
+  if (rows.length === 0)
+    return [issue("csv_empty", "CSV has no rows", path)];
+  const columns = rows[0].length;
+  const inconsistent = rows.findIndex((row) => row.length !== columns);
+  return inconsistent < 0 ? [] : [
+    issue("csv_column_mismatch", `CSV row ${inconsistent + 1} has ${rows[inconsistent].length} columns; expected ${columns}`, path)
+  ];
+};
+var validateEmail = (data, path) => {
+  const value = decode(data).replace(/\r\n?/g, `
+`);
+  const separator = value.indexOf(`
+
+`);
+  if (separator < 0) {
+    return [
+      issue("email_missing_body_separator", "Email must contain headers followed by a blank line and body", path)
+    ];
+  }
+  const headers = value.slice(0, separator);
+  const required = ["to", "subject"].filter((name) => !new RegExp(`^${name}:\\s*\\S+`, "imu").test(headers));
+  return required.map((name) => issue("email_missing_header", `Email is missing a non-empty ${name} header`, path));
+};
+var validateXml = (value) => {
+  const stack = [];
+  const withoutOpaqueSections = value.replace(/<!--[\s\S]*?-->/gu, "").replace(/<!\[CDATA\[[\s\S]*?\]\]>/gu, "").replace(/<\?[\s\S]*?\?>/gu, "");
+  for (const match of withoutOpaqueSections.matchAll(/<\s*(\/?)\s*([\w:.-]+)([^>]*)>/gu)) {
+    const closing = match[1] === "/";
+    const name = match[2];
+    const suffix = match[3] ?? "";
+    if (!closing && suffix.trimEnd().endsWith("/"))
+      continue;
+    if (!closing) {
+      stack.push(name);
+      continue;
+    }
+    const expected = stack.pop();
+    if (expected !== name) {
+      throw new Error(expected ? `expected closing tag for <${expected}> but found </${name}>` : `unexpected closing tag </${name}>`);
+    }
+  }
+  if (stack.length > 0)
+    throw new Error(`unclosed tag <${stack.at(-1)}>`);
+};
+var validateZip = (data, path, officePresentation) => {
+  let entries;
+  try {
+    entries = unzipSync(data);
+  } catch (error) {
+    return [
+      issue("zip_invalid", `ZIP archive could not be opened: ${error instanceof Error ? error.message : String(error)}`, path)
+    ];
+  }
+  const names = Object.keys(entries).filter((name) => !name.endsWith("/"));
+  if (names.length === 0) {
+    return [issue("zip_empty", "ZIP archive has no files", path)];
+  }
+  if (!officePresentation)
+    return [];
+  const required = ["[Content_Types].xml", "ppt/presentation.xml"];
+  const missing = required.filter((name) => !entries[name]);
+  if (!names.some((name) => /^ppt\/slides\/slide\d+\.xml$/u.test(name))) {
+    missing.push("ppt/slides/slide*.xml");
+  }
+  const issues = missing.map((name) => issue("presentation_entry_missing", `Presentation is missing ${name}`, path));
+  for (const name of names.filter((candidate) => candidate.endsWith(".xml") || candidate.endsWith(".rels"))) {
+    try {
+      validateXml(decode(entries[name]));
+    } catch (error) {
+      issues.push(issue("presentation_xml_invalid", `${name}: ${error instanceof Error ? error.message : String(error)}`, path));
+    }
+  }
+  return issues;
+};
+var validateGeneratedArtifactFormats = (result) => (result.assets ?? []).flatMap((asset, index) => {
+  const mediaType = asset.mediaType.toLowerCase();
+  const path = `assets[${index}](${asset.name})`;
+  try {
+    if (mediaType.includes("csv"))
+      return validateCsv(asset.data, path);
+    if (mediaType === "message/rfc822")
+      return validateEmail(asset.data, path);
+    if (mediaType.includes("presentationml.presentation")) {
+      return validateZip(asset.data, path, true);
+    }
+    if (mediaType.includes("zip"))
+      return validateZip(asset.data, path, false);
+    return [];
+  } catch (error) {
+    return [
+      issue("format_invalid", error instanceof Error ? error.message : String(error), path)
+    ];
+  }
+});
 // src/standardKinds.ts
 import { Type } from "typebox";
 var FileArtifactContentSchema = Type.Object({
@@ -192,6 +792,7 @@ var createArtifactService = (options) => {
   const now = () => (options.clock ?? (() => new Date))().toISOString();
   const idFactory = options.idFactory ?? (() => crypto.randomUUID());
   const eventIdFactory = options.eventIdFactory ?? (() => crypto.randomUUID());
+  const batchIdFactory = options.batchIdFactory ?? (() => crypto.randomUUID());
   const event = (artifact, type, payload) => ({
     artifactId: artifact.id,
     createdAt: now(),
@@ -391,6 +992,231 @@ var createArtifactService = (options) => {
         throw error;
       }
     },
+    stageBatch: async (ownerId, input, stageOptions = {}) => {
+      if (input.items.length === 0) {
+        throw new ArtifactError("invalid_content", "An artifact batch must contain at least one artifact");
+      }
+      const keys = input.items.map((item) => item.key.trim());
+      if (keys.some((key) => key.length === 0) || new Set(keys).size !== keys.length) {
+        throw new ArtifactError("invalid_content", "Artifact batch item keys must be non-empty and unique");
+      }
+      const bundleId = input.bundleId ?? batchIdFactory();
+      const stagedAt = now();
+      const sharedEvidence = input.evidence ?? [];
+      const staged = [];
+      const evidenceJson = (evidence) => evidence.map((reference) => ({
+        ...reference.capturedAt ? { capturedAt: reference.capturedAt } : {},
+        ...reference.excerpt ? { excerpt: reference.excerpt } : {},
+        ...reference.metadata ? { metadata: reference.metadata } : {},
+        ...reference.sourceId ? { sourceId: reference.sourceId } : {},
+        ...reference.sourceUrl ? { sourceUrl: reference.sourceUrl } : {}
+      }));
+      try {
+        for (const [index, item] of input.items.entries()) {
+          const { assets: assetInputs = [], ...artifactInput } = item.artifact;
+          validateAssetInputs(item.artifact.kind, assetInputs);
+          const evidence = [...sharedEvidence, ...item.evidence ?? []];
+          const provisional = buildRecord(ownerId, {
+            ...artifactInput,
+            metadata: {
+              ...input.metadata,
+              ...artifactInput.metadata,
+              artifactBatch: {
+                bundleId,
+                evidence: evidenceJson(evidence),
+                itemKey: item.key
+              }
+            },
+            provenance: {
+              ...input.provenance,
+              ...artifactInput.provenance,
+              evidence,
+              sourceIds: [
+                ...new Set([
+                  ...input.provenance?.sourceIds ?? [],
+                  ...artifactInput.provenance?.sourceIds ?? [],
+                  ...evidence.flatMap((reference) => reference.sourceId ? [reference.sourceId] : [])
+                ])
+              ]
+            }
+          }, []);
+          if (assetInputs.length === 0) {
+            staged.push({ evidence, key: item.key, record: provisional });
+            continue;
+          }
+          const assetStore = requireAssetTransactions();
+          const transaction = await assetStore.stage(assetInputs, {
+            artifact: provisional,
+            idempotencyKey: `artifact-batch:${bundleId}:${index}`
+          });
+          staged.push({
+            evidence,
+            key: item.key,
+            record: {
+              ...provisional,
+              assets: validateAssets(item.artifact.kind, transaction.references)
+            },
+            transaction
+          });
+        }
+      } catch (error) {
+        await Promise.allSettled(staged.map((item) => item.transaction?.rollback()));
+        throw error;
+      }
+      let validationIssues;
+      try {
+        validationIssues = (await Promise.all((stageOptions.validators ?? []).map((validate) => validate({
+          bundleId,
+          evidence: sharedEvidence,
+          items: staged,
+          ownerId
+        })))).flat();
+      } catch (error) {
+        await Promise.allSettled(staged.map((item) => item.transaction?.rollback()));
+        throw error;
+      }
+      const validation = validationIssues.length === 0 ? { valid: true } : { issues: validationIssues, valid: false };
+      let settled;
+      const receiptItems = () => staged.map(({ key, record }) => ({
+        artifactId: record.id,
+        key,
+        kind: record.kind,
+        revision: record.revision,
+        title: record.title
+      }));
+      const finish = (partial) => {
+        settled = {
+          bundleId,
+          completedAt: now(),
+          items: partial.items ?? receiptItems(),
+          ownerId,
+          stagedAt,
+          validation,
+          ...partial
+        };
+        return settled;
+      };
+      const rollbackTransactions = async (candidates = staged) => {
+        const failures = [];
+        for (const item of candidates) {
+          if (!item.transaction)
+            continue;
+          try {
+            await item.transaction.rollback();
+          } catch {
+            failures.push(item.key);
+          }
+        }
+        return failures;
+      };
+      if (!validation.valid) {
+        const failures = await rollbackTransactions();
+        finish({
+          archivedArtifactIds: [],
+          atomic: Boolean(options.store.createBatch),
+          error: failures.length === 0 ? "Artifact batch validation failed" : `Artifact batch validation failed; asset rollback failed for: ${failures.join(", ")}`,
+          status: failures.length === 0 ? "rolled_back" : "partial_failure"
+        });
+      }
+      return {
+        bundleId,
+        commit: async () => {
+          if (settled)
+            return settled;
+          const transactions = staged.flatMap((item) => item.transaction ? [item.transaction] : []);
+          const entries = staged.map(({ key, record }) => ({
+            events: [
+              event(record, "artifact.created", { bundleId, itemKey: key }),
+              event(record, "artifact.generated", { bundleId, itemKey: key })
+            ],
+            record
+          }));
+          if (options.store.createBatch) {
+            try {
+              for (const transaction of transactions)
+                await transaction.commit();
+              await options.store.createBatch(entries);
+              return finish({
+                archivedArtifactIds: [],
+                atomic: true,
+                status: "committed"
+              });
+            } catch (error) {
+              const failures = await rollbackTransactions();
+              return finish({
+                archivedArtifactIds: [],
+                atomic: true,
+                error: error instanceof Error ? error.message : String(error),
+                status: failures.length === 0 ? "rolled_back" : "partial_failure"
+              });
+            }
+          }
+          if ((input.commitMode ?? "require_atomic") === "require_atomic") {
+            const failures = await rollbackTransactions();
+            return finish({
+              archivedArtifactIds: [],
+              atomic: false,
+              error: "The configured artifact store does not support atomic batches",
+              status: failures.length === 0 ? "rolled_back" : "partial_failure"
+            });
+          }
+          const created = [];
+          try {
+            for (const transaction of transactions)
+              await transaction.commit();
+            for (const [index, entry] of entries.entries()) {
+              await options.store.create(entry.record, entry.events);
+              created.push(staged[index]);
+            }
+            return finish({
+              archivedArtifactIds: [],
+              atomic: false,
+              status: "committed"
+            });
+          } catch (error) {
+            const archivedArtifactIds = [];
+            const archiveFailures = [];
+            for (const item of created) {
+              try {
+                await service.archive(ownerId, item.record.id);
+                archivedArtifactIds.push(item.record.id);
+              } catch {
+                archiveFailures.push(item.record.id);
+              }
+            }
+            const uncreated = staged.filter((item) => !created.includes(item));
+            const rollbackFailures = await rollbackTransactions(uncreated);
+            const failed = [...archiveFailures, ...rollbackFailures];
+            return finish({
+              archivedArtifactIds,
+              atomic: false,
+              error: error instanceof Error ? error.message : String(error),
+              items: receiptItems().map((item) => ({
+                ...item,
+                ...archivedArtifactIds.includes(item.artifactId) ? { archived: true } : {}
+              })),
+              status: failed.length === 0 ? "rolled_back" : "partial_failure"
+            });
+          }
+        },
+        evidence: sharedEvidence,
+        items: staged,
+        ownerId,
+        rollback: async (reason = "Artifact batch rolled back before commit") => {
+          if (settled)
+            return settled;
+          const failures = await rollbackTransactions();
+          return finish({
+            archivedArtifactIds: [],
+            atomic: Boolean(options.store.createBatch),
+            error: failures.length === 0 ? reason : `${reason}; asset rollback failed for: ${failures.join(", ")}`,
+            status: failures.length === 0 ? "rolled_back" : "partial_failure"
+          });
+        },
+        stagedAt,
+        validation
+      };
+    },
     detach: async (ownerId, artifactId, assetId, expectedRevision) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "attach");
@@ -650,6 +1476,21 @@ var createMemoryArtifactStore = (initial = []) => {
       for (const event of newEvents)
         events.set(event.id, clone(event));
     },
+    createBatch: async (entries) => {
+      const ids = entries.map(({ record }) => record.id);
+      if (new Set(ids).size !== ids.length) {
+        throw new Error("Duplicate artifact id in batch");
+      }
+      const duplicate = ids.find((id) => records.has(id));
+      if (duplicate)
+        throw new Error(`Duplicate artifact id: ${duplicate}`);
+      for (const { events: newEvents = [], record } of entries) {
+        records.set(record.id, clone(record));
+        revisions.set(record.id, [clone(record)]);
+        for (const event of newEvents)
+          events.set(event.id, clone(event));
+      }
+    },
     get: async (ownerId, artifactId) => {
       const record = records.get(artifactId);
       return record?.ownerId === ownerId ? clone(record) : null;
@@ -855,17 +1696,18 @@ var createArtifactTools = (options) => ({
   }
 });
 export {
-  standardArtifactDefinitions,
-  isJsonValue,
-  defineArtifactRegistry,
-  createMemoryArtifactStore,
-  createMemoryArtifactAssetStore,
-  createArtifactTools,
-  createArtifactService,
-  createArtifactRendererRegistry,
-  createArtifactGeneratorRegistry,
-  STANDARD_ARTIFACT_KIND_NAMES,
-  ArtifactError,
+  ARTIFACT_EVENT_TYPES,
   ARTIFACT_STATUSES,
-  ARTIFACT_EVENT_TYPES
+  ArtifactError,
+  STANDARD_ARTIFACT_KIND_NAMES,
+  createArtifactGeneratorRegistry,
+  createArtifactRendererRegistry,
+  createArtifactService,
+  createArtifactTools,
+  createMemoryArtifactAssetStore,
+  createMemoryArtifactStore,
+  defineArtifactRegistry,
+  isJsonValue,
+  standardArtifactDefinitions,
+  validateGeneratedArtifactFormats
 };