@absolutejs/artifacts 0.2.0 → 0.3.0

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
@@ -192,6 +232,27 @@ const deck = await generators.generate(artifacts, {
 });
 ```
 
+Generators may expose a `validate` function. The bundled
+`validateGeneratedArtifactFormats` validator checks CSV row structure, RFC 822
+headers, ZIP readability, and PPTX package/XML integrity before persistence.
+Generate several independent artifacts with one atomic receipt through the same
+registry:
+
+```ts
+const receipt = await generators.generateBatch(artifacts, {
+  ownerId: member.id,
+  items: [
+    { createdBy: "agent", key: "deck", kind: "presentation", title: "Deck" },
+    { createdBy: "agent", key: "email", kind: "email", title: "Email" },
+  ],
+  provenance: { tool: "campaign_generator" },
+});
+```
+
+Generation validators run after every output is staged and before anything is
+committed. Validation failures return a rolled-back completion receipt keyed to
+the invalid output.
+
 ## RAG ingestion
 
 The optional `@absolutejs/artifacts/rag` entry point resolves one current or
@@ -210,7 +271,10 @@ const upsert = await buildRAGUpsertInputFromUploads({ uploads });
 
 `createArtifactRAGIndexCoordinator` wraps that conversion with durable
 `pending`, `indexed`, and `failed` state. It removes document IDs from the
-previous indexed revision after the replacement succeeds.
+previous indexed revision after the replacement succeeds. Set `failureMode` to
+`"isolate_uploads"` to index structured content and assets independently. A bad
+asset then produces a typed partial receipt while preserving successful
+document ids; obsolete ids are removed only after a fully successful revision.
 
 ## Events and retention
 

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
 };