@absolutejs/artifacts 0.2.0 → 0.2.1

package/README.md

@@ -24,6 +24,7 @@ routes, authorization, UI, or hosting.
   datasets, code, images, audio, video, email, archives, and generic files
 - An optional bridge to `@absolutejs/rag` ingestion
 - Provider-neutral generation registries with atomic multi-file bundles
+- Staged, validate-before-commit multi-artifact batches with completion receipts
 - Revision-pinned or explicitly live publications
 - Durable lifecycle events designed for transactional outboxes
 - Per-revision RAG indexing state and an indexing coordinator
@@ -169,6 +170,45 @@ const report = await artifacts.createBundle("owner-123", {
 });
 ```
 
+When one job must produce several artifacts together, stage the complete batch,
+run domain validators before persistence, and commit it through a store that
+implements `createBatch` (the package Drizzle and memory stores do):
+
+```ts
+const staged = await artifacts.stageBatch(
+  "owner-123",
+  {
+    evidence: [{ sourceId: "research-run-123", sourceUrl: sourceUrl }],
+    items: [
+      { artifact: worksheetInput, key: "worksheet" },
+      { artifact: reportInput, key: "report" },
+    ],
+    provenance: { tool: "prospecting_mission", traceId: mission.id },
+  },
+  {
+    validators: [
+      ({ items }) =>
+        validateDomainEvidence(items).map((message) => ({
+          code: "evidence_invalid",
+          message,
+        })),
+    ],
+  },
+);
+
+const receipt = await staged.commit();
+if (receipt.status !== "committed") throw new Error(receipt.error);
+```
+
+Every artifact carries its batch id, item key, evidence, and provenance.
+`commit()` returns the durable reconciliation receipt: artifact ids,
+revisions, atomicity, validation outcome, and any archived compensation. The
+default mode requires an atomic `ArtifactStore.createBatch`. Hosts that cannot
+provide a transaction may explicitly select `archive_on_failure`; completed
+earlier writes are then archived and reported as `rolled_back` or
+`partial_failure`. Calling `rollback()` before commit releases all staged
+asset transactions.
+
 ## Generation
 
 Generators are provider-neutral. They return validated structured content and

package/dist/drizzle.js

@@ -145,6 +145,17 @@ var createDrizzleArtifactStore = (options) => ({
     if (events.length > 0)
       await transaction.insert(artifactEvents).values(eventRows(events));
   }),
+  createBatch: (entries) => options.db.transaction(async (transaction) => {
+    if (entries.length === 0)
+      return;
+    for (const { events: events2 = [], record } of entries)
+      assertEventsBelongToArtifact(record, events2);
+    await transaction.insert(artifactRecords).values(entries.map(({ record }) => recordRow(record)));
+    await transaction.insert(artifactRevisions).values(entries.map(({ record }) => revisionRow(record)));
+    const events = entries.flatMap((entry) => entry.events ?? []);
+    if (events.length > 0)
+      await transaction.insert(artifactEvents).values(eventRows(events));
+  }),
   get: async (ownerId, artifactId) => {
     const [row] = await options.db.select({ document: artifactRecords.document }).from(artifactRecords).where(and(eq(artifactRecords.id, artifactId), eq(artifactRecords.ownerId, ownerId))).limit(1);
     return row?.document ?? null;
@@ -235,18 +246,18 @@ var createDrizzleArtifactStore = (options) => ({
   })
 });
 export {
-  createDrizzleArtifactStore,
-  artifactRevisions,
-  artifactRecords,
-  artifactIndexingStates,
-  artifactEvents,
-  artifactDrizzleSchema,
-  ArtifactRevisionSelectSchema,
-  ArtifactRevisionInsertSchema,
-  ArtifactRecordSelectSchema,
-  ArtifactRecordInsertSchema,
-  ArtifactIndexingStateSelectSchema,
-  ArtifactIndexingStateInsertSchema,
+  ArtifactEventInsertSchema,
   ArtifactEventSelectSchema,
-  ArtifactEventInsertSchema
+  ArtifactIndexingStateInsertSchema,
+  ArtifactIndexingStateSelectSchema,
+  ArtifactRecordInsertSchema,
+  ArtifactRecordSelectSchema,
+  ArtifactRevisionInsertSchema,
+  ArtifactRevisionSelectSchema,
+  artifactDrizzleSchema,
+  artifactEvents,
+  artifactIndexingStates,
+  artifactRecords,
+  artifactRevisions,
+  createDrizzleArtifactStore
 };

package/dist/index.js

@@ -192,6 +192,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 +392,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 +876,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 +1096,17 @@ 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
 };

package/dist/manifest.js

@@ -1,5 +1,5 @@
 // @bun
-// ../manifest/dist/index.js
+// node_modules/@absolutejs/manifest/dist/index.js
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { Type as Type2 } from "typebox";

package/dist/rag.js

@@ -75,6 +75,6 @@ var createArtifactRAGIndexCoordinator = (options) => ({
   }
 });
 export {
-  createArtifactRAGIndexCoordinator,
-  artifactToRAGUploads
+  artifactToRAGUploads,
+  createArtifactRAGIndexCoordinator
 };

package/dist/src/index.d.ts

@@ -13,4 +13,4 @@ export { createArtifactRendererRegistry, type ArtifactRenderer, type ArtifactRen
 export { createArtifactService, type ArtifactPublisher, type ArtifactService, type ArtifactServiceOptions, } from "./service";
 export { createMemoryArtifactStore, createMemoryArtifactAssetStore, type ArtifactAssetStore, type ArtifactAssetTransaction, type ArtifactStore, } from "./store";
 export { createArtifactTools, type ArtifactToolDefinition, type ArtifactToolMap, type ArtifactToolOptions, } from "./tools";
-export { ARTIFACT_STATUSES, ARTIFACT_EVENT_TYPES, ArtifactError, isJsonValue, type ArtifactAssetReference, type ArtifactAssetRole, type ArtifactAssetWriteInput, type ArtifactBundleCreateInput, type ArtifactCapability, type ArtifactCreateInput, type ArtifactErrorCode, type ArtifactEvent, type ArtifactEventQuery, type ArtifactEventType, type ArtifactGarbageCollectionResult, type ArtifactIndexingState, type ArtifactIndexingStatus, type ArtifactListQuery, type ArtifactLineageReference, type ArtifactLineageRelation, type ArtifactProvenance, type ArtifactPublication, type ArtifactPublishInput, type ArtifactRecord, type ArtifactRevision, type ArtifactRetentionCandidate, type ArtifactStatus, type ArtifactUpdateInput, type JsonObject, type JsonPrimitive, type JsonValue, } from "./types";
+export { ARTIFACT_STATUSES, ARTIFACT_EVENT_TYPES, ArtifactError, isJsonValue, type ArtifactAssetReference, type ArtifactAssetRole, type ArtifactAssetWriteInput, type ArtifactBatchCommitMode, type ArtifactBatchCompletionReceipt, type ArtifactBatchCreateInput, type ArtifactBatchItemInput, type ArtifactBatchReceiptItem, type ArtifactBatchValidationIssue, type ArtifactBatchValidationResult, type ArtifactBatchValidator, type ArtifactBundleCreateInput, type ArtifactCapability, type ArtifactCreateInput, type ArtifactErrorCode, type ArtifactEvent, type ArtifactEventQuery, type ArtifactEventType, type ArtifactEvidenceReference, type ArtifactGarbageCollectionResult, type ArtifactIndexingState, type ArtifactIndexingStatus, type ArtifactListQuery, type ArtifactLineageReference, type ArtifactLineageRelation, type ArtifactProvenance, type ArtifactPublication, type ArtifactPublishInput, type ArtifactRecord, type ArtifactRevision, type ArtifactRetentionCandidate, type ArtifactStatus, type ArtifactUpdateInput, type JsonObject, type JsonPrimitive, type JsonValue, type StagedArtifactBatch, } from "./types";

package/dist/src/manifest.d.ts

@@ -9,6 +9,9 @@ export declare const manifest: Omit<import("@absolutejs/manifest").PackageManife
     }) => Promise<import("./types").ArtifactGarbageCollectionResult>;
     create: (ownerId: string, input: import("./types").ArtifactCreateInput) => Promise<import("./types").ArtifactRecord>;
     createBundle: (ownerId: string, input: import("./types").ArtifactBundleCreateInput) => Promise<import("./types").ArtifactRecord>;
+    stageBatch: (ownerId: string, input: import("./types").ArtifactBatchCreateInput, stageOptions?: {
+        validators?: import("./types").ArtifactBatchValidator[];
+    }) => Promise<import("./types").StagedArtifactBatch>;
     detach: (ownerId: string, artifactId: string, assetId: string, expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
     get: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
     getIndexingState: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactIndexingState | null>;
@@ -44,6 +47,9 @@ export declare const manifest: Omit<import("@absolutejs/manifest").PackageManife
         }) => Promise<import("./types").ArtifactGarbageCollectionResult>;
         create: (ownerId: string, input: import("./types").ArtifactCreateInput) => Promise<import("./types").ArtifactRecord>;
         createBundle: (ownerId: string, input: import("./types").ArtifactBundleCreateInput) => Promise<import("./types").ArtifactRecord>;
+        stageBatch: (ownerId: string, input: import("./types").ArtifactBatchCreateInput, stageOptions?: {
+            validators?: import("./types").ArtifactBatchValidator[];
+        }) => Promise<import("./types").StagedArtifactBatch>;
         detach: (ownerId: string, artifactId: string, assetId: string, expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
         get: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
         getIndexingState: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactIndexingState | null>;
@@ -80,6 +86,9 @@ export declare const manifest: Omit<import("@absolutejs/manifest").PackageManife
         }) => Promise<import("./types").ArtifactGarbageCollectionResult>;
         create: (ownerId: string, input: import("./types").ArtifactCreateInput) => Promise<import("./types").ArtifactRecord>;
         createBundle: (ownerId: string, input: import("./types").ArtifactBundleCreateInput) => Promise<import("./types").ArtifactRecord>;
+        stageBatch: (ownerId: string, input: import("./types").ArtifactBatchCreateInput, stageOptions?: {
+            validators?: import("./types").ArtifactBatchValidator[];
+        }) => Promise<import("./types").StagedArtifactBatch>;
         detach: (ownerId: string, artifactId: string, assetId: string, expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
         get: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
         getIndexingState: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactIndexingState | null>;

package/dist/src/service.d.ts

@@ -1,6 +1,6 @@
 import type { ArtifactKindDefinitions, ArtifactRegistry } from "./registry";
 import type { ArtifactAssetStore, ArtifactStore } from "./store";
-import { type ArtifactAssetReference, type ArtifactAssetWriteInput, type ArtifactBundleCreateInput, type ArtifactCreateInput, type ArtifactEvent, type ArtifactEventQuery, type ArtifactGarbageCollectionResult, type ArtifactIndexingState, type ArtifactIndexingStatus, type ArtifactListQuery, type ArtifactPublishInput, type ArtifactRecord, type ArtifactUpdateInput } from "./types";
+import { type ArtifactAssetReference, type ArtifactAssetWriteInput, type ArtifactBatchCreateInput, type ArtifactBatchValidator, type ArtifactBundleCreateInput, type ArtifactCreateInput, type ArtifactEvent, type ArtifactEventQuery, type ArtifactGarbageCollectionResult, type ArtifactIndexingState, type ArtifactIndexingStatus, type ArtifactListQuery, type ArtifactPublishInput, type ArtifactRecord, type ArtifactUpdateInput, type StagedArtifactBatch } from "./types";
 export type ArtifactPublisher = {
     publish(artifact: ArtifactRecord, options: {
         idempotencyKey: string;
@@ -16,6 +16,7 @@ export type ArtifactPublisher = {
 };
 export type ArtifactServiceOptions<TDefinitions extends ArtifactKindDefinitions = ArtifactKindDefinitions> = {
     assetStore?: ArtifactAssetStore;
+    batchIdFactory?: () => string;
     clock?: () => Date;
     eventIdFactory?: () => string;
     idFactory?: () => string;
@@ -34,6 +35,9 @@ export declare const createArtifactService: <TDefinitions extends ArtifactKindDe
     }) => Promise<ArtifactGarbageCollectionResult>;
     create: (ownerId: string, input: ArtifactCreateInput) => Promise<ArtifactRecord>;
     createBundle: (ownerId: string, input: ArtifactBundleCreateInput) => Promise<ArtifactRecord>;
+    stageBatch: (ownerId: string, input: ArtifactBatchCreateInput, stageOptions?: {
+        validators?: ArtifactBatchValidator[];
+    }) => Promise<StagedArtifactBatch>;
     detach: (ownerId: string, artifactId: string, assetId: string, expectedRevision?: number) => Promise<ArtifactRecord>;
     get: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
     getIndexingState: (ownerId: string, artifactId: string) => Promise<ArtifactIndexingState | null>;

package/dist/src/store.d.ts

@@ -22,6 +22,11 @@ export type ArtifactAssetStore = {
 export type ArtifactStore = {
     /** Persist the current record and its first immutable revision atomically. */
     create(record: ArtifactRecord, events?: ArtifactEvent[]): Promise<void>;
+    /** Persist multiple records, first revisions, and events in one transaction. */
+    createBatch?(entries: Array<{
+        events?: ArtifactEvent[];
+        record: ArtifactRecord;
+    }>): Promise<void>;
     getIndexingState(ownerId: string, artifactId: string): Promise<ArtifactIndexingState | null>;
     get(ownerId: string, artifactId: string): Promise<ArtifactRecord | null>;
     getRevision(ownerId: string, artifactId: string, revision: number): Promise<ArtifactRevision | null>;

package/dist/src/types.d.ts

@@ -8,12 +8,20 @@ export declare function isJsonValue(value: unknown): value is JsonValue;
 export type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];
 export type ArtifactCapability = "attach" | "archive" | "edit" | "export" | "preview" | "publish" | "refine";
 export type ArtifactProvenance = {
+    evidence?: ArtifactEvidenceReference[];
     lineage?: ArtifactLineageReference[];
     model?: string;
     sourceIds?: string[];
     tool?: string;
     traceId?: string;
 };
+export type ArtifactEvidenceReference = {
+    capturedAt?: string;
+    excerpt?: string;
+    metadata?: JsonObject;
+    sourceId?: string;
+    sourceUrl?: string;
+};
 export type ArtifactLineageRelation = "derived_from" | "generated_from" | "references" | "replaces";
 export type ArtifactLineageReference = {
     artifactId?: string;
@@ -122,6 +130,78 @@ export type ArtifactUpdateInput = {
 export type ArtifactBundleCreateInput = Omit<ArtifactCreateInput, "assets"> & {
     assets?: ArtifactAssetWriteInput[];
 };
+export type ArtifactBatchItemInput = {
+    artifact: ArtifactBundleCreateInput;
+    evidence?: ArtifactEvidenceReference[];
+    /** Stable caller-defined key used to reconcile a receipt with requested output. */
+    key: string;
+};
+export type ArtifactBatchCommitMode = "archive_on_failure" | "require_atomic";
+export type ArtifactBatchCreateInput = {
+    bundleId?: string;
+    commitMode?: ArtifactBatchCommitMode;
+    evidence?: ArtifactEvidenceReference[];
+    items: ArtifactBatchItemInput[];
+    metadata?: JsonObject;
+    provenance?: ArtifactProvenance;
+};
+export type ArtifactBatchValidationIssue = {
+    code: string;
+    itemKey?: string;
+    message: string;
+    path?: string;
+};
+export type ArtifactBatchValidationResult = {
+    issues?: never;
+    valid: true;
+} | {
+    issues: ArtifactBatchValidationIssue[];
+    valid: false;
+};
+export type ArtifactBatchReceiptItem = {
+    artifactId: string;
+    archived?: boolean;
+    key: string;
+    kind: string;
+    revision: number;
+    title: string;
+};
+export type ArtifactBatchCompletionReceipt = {
+    archivedArtifactIds: string[];
+    atomic: boolean;
+    bundleId: string;
+    completedAt: string;
+    error?: string;
+    items: ArtifactBatchReceiptItem[];
+    ownerId: string;
+    stagedAt: string;
+    status: "committed" | "partial_failure" | "rolled_back";
+    validation: ArtifactBatchValidationResult;
+};
+export type ArtifactBatchValidator = (context: {
+    bundleId: string;
+    evidence: ArtifactEvidenceReference[];
+    items: ReadonlyArray<{
+        evidence: ArtifactEvidenceReference[];
+        key: string;
+        record: Readonly<ArtifactRecord>;
+    }>;
+    ownerId: string;
+}) => ArtifactBatchValidationIssue[] | Promise<ArtifactBatchValidationIssue[]>;
+export type StagedArtifactBatch = {
+    bundleId: string;
+    commit(): Promise<ArtifactBatchCompletionReceipt>;
+    evidence: ArtifactEvidenceReference[];
+    items: ReadonlyArray<{
+        evidence: ArtifactEvidenceReference[];
+        key: string;
+        record: Readonly<ArtifactRecord>;
+    }>;
+    ownerId: string;
+    rollback(reason?: string): Promise<ArtifactBatchCompletionReceipt>;
+    stagedAt: string;
+    validation: ArtifactBatchValidationResult;
+};
 export type ArtifactPublishInput = {
     mode?: "live" | "pinned";
 };
@@ -133,7 +213,7 @@ export type ArtifactGarbageCollectionResult = {
     deleted: ArtifactAssetReference[];
     retained: ArtifactAssetReference[];
 };
-export type ArtifactErrorCode = "asset_store_unavailable" | "asset_transaction_unavailable" | "conflict" | "generator_unavailable" | "invalid_content" | "not_found" | "publisher_unavailable" | "renderer_unavailable" | "unsupported_capability" | "unknown_kind";
+export type ArtifactErrorCode = "asset_store_unavailable" | "asset_transaction_unavailable" | "atomic_batch_unavailable" | "batch_validation_failed" | "conflict" | "generator_unavailable" | "invalid_content" | "not_found" | "publisher_unavailable" | "renderer_unavailable" | "unsupported_capability" | "unknown_kind";
 export declare class ArtifactError extends Error {
     readonly code: ArtifactErrorCode;
     constructor(code: ArtifactErrorCode, message: string);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/artifacts",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Typed, versioned artifacts for AI products — schemas, lifecycle, storage, rendering, publishing, revisions, and agent tools without prescribing a database or host.",
   "author": "Alex Kahn",
   "license": "BUSL-1.1",