@absolutejs/artifacts 0.1.5 → 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

@@ -1,6 +1,6 @@
 // @bun
 // src/registry.ts
-import { Value } from "@sinclair/typebox/value";
+import { Value } from "typebox/value";
 
 // src/types.ts
 var ARTIFACT_STATUSES = ["draft", "published", "archived"];
@@ -49,7 +49,7 @@ var defineArtifactRegistry = (definitions) => ({
     }
     if (!Value.Check(definition.content, content) || !isJsonValue(content)) {
       const issue = [...Value.Errors(definition.content, content)][0];
-      const detail = issue ? `${issue.path || "/"}: ${issue.message}` : "invalid content";
+      const detail = issue ? `${issue.instancePath || "/"}: ${issue.message}` : "invalid content";
       throw new ArtifactError("invalid_content", `Invalid ${kind} artifact content (${detail})`);
     }
     return content;
@@ -88,7 +88,7 @@ var createArtifactGeneratorRegistry = (initial = []) => {
   };
 };
 // src/standardKinds.ts
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 var FileArtifactContentSchema = Type.Object({
   description: Type.Optional(Type.String()),
   instructions: Type.Optional(Type.String()),
@@ -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;
@@ -722,15 +963,17 @@ var createMemoryArtifactStore = (initial = []) => {
   };
 };
 // src/tools.ts
-import { Type as Type2 } from "@sinclair/typebox";
-var JsonValueSchema = Type2.Recursive((self) => Type2.Union([
-  Type2.String(),
-  Type2.Number(),
-  Type2.Boolean(),
-  Type2.Null(),
-  Type2.Array(self),
-  Type2.Record(Type2.String(), self)
-]));
+import { Type as Type2 } from "typebox";
+var JsonValueSchema = Type2.Cyclic({
+  JsonValue: Type2.Union([
+    Type2.String(),
+    Type2.Number(),
+    Type2.Boolean(),
+    Type2.Null(),
+    Type2.Array(Type2.Ref("JsonValue")),
+    Type2.Record(Type2.String(), Type2.Ref("JsonValue"))
+  ])
+}, "JsonValue");
 var record = (input) => isJsonValue(input) && input !== null && typeof input === "object" && !Array.isArray(input) ? input : {};
 var stringValue = (input, key) => typeof input[key] === "string" ? input[key] : undefined;
 var createArtifactTools = (options) => ({
@@ -853,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
 };