@absolutejs/artifacts 0.0.2 → 0.0.4

package/README.md

@@ -23,6 +23,11 @@ routes, authorization, UI, or hosting.
 - Standard file-backed kinds for documents, presentations, spreadsheets,
   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
+- Revision-pinned or explicitly live publications
+- Durable lifecycle events designed for transactional outboxes
+- Per-revision RAG indexing state and an indexing coordinator
+- Artifact/source lineage and history-aware asset garbage collection
 
 Your application retains authorization, durable persistence, public tokens,
 URLs, notifications, analytics, submissions, and product-specific rendering.
@@ -121,6 +126,46 @@ await artifacts.attach("owner-123", report.id, {
 });
 ```
 
+Multiple generated files should use one staged transaction and therefore one
+artifact revision:
+
+```ts
+const report = await artifacts.createBundle("owner-123", {
+  assets: [pdfOutput, docxOutput, thumbnailOutput],
+  content: { summary: "Quarterly results" },
+  createdBy: "agent",
+  kind: "document",
+  provenance: {
+    lineage: [{ relation: "generated_from", sourceId: "rag-document-123" }],
+    tool: "quarterly_report_generator",
+  },
+  title: "Q3 report",
+});
+```
+
+## Generation
+
+Generators are provider-neutral. They return validated structured content and
+zero or more file writes; the registry commits those outputs through the same
+artifact bundle lifecycle:
+
+```ts
+const generators = createArtifactGeneratorRegistry([
+  {
+    kind: "presentation",
+    name: "company-deck",
+    generate: async ({ prompt }) => buildPresentation(prompt),
+  },
+]);
+
+const deck = await generators.generate(artifacts, {
+  createdBy: "agent",
+  kind: "presentation",
+  ownerId: member.id,
+  prompt: "Build the partner launch deck",
+});
+```
+
 ## RAG ingestion
 
 The optional `@absolutejs/artifacts/rag` entry point resolves one current or
@@ -137,6 +182,22 @@ const uploads = await artifactToRAGUploads(revision, assetStore);
 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.
+
+## Events and retention
+
+Every lifecycle mutation supplies its event to the artifact store in the same
+call that writes the current record and immutable revision. Durable adapters
+should commit those rows in one database transaction, then workers can consume
+unprocessed events for RAG indexing, previews, notifications, scanning, or
+conversion.
+
+Asset collection compares storage candidates with references across every
+retained revision. `collectAssetGarbage({ dryRun: true })` previews deletion;
+only unreferenced objects older than the configured minimum age are eligible.
+
 ## Compose publishing and rendering
 
 Publishing is an adapter because public access is a host policy:
@@ -154,6 +215,10 @@ const artifacts = createArtifactService({
 });
 ```
 
+Publishing defaults to `pinned`: the public record names the exact immutable
+revision. `mode: "live"` is an explicit alternative whose revision advances
+with later edits.
+
 Renderers are independently registered by artifact kind and output format:
 
 ```ts

package/dist/index.js

@@ -4,6 +4,18 @@ import { Value } from "@sinclair/typebox/value";
 
 // src/types.ts
 var ARTIFACT_STATUSES = ["draft", "published", "archived"];
+var ARTIFACT_EVENT_TYPES = [
+  "artifact.archived",
+  "artifact.asset_attached",
+  "artifact.asset_detached",
+  "artifact.created",
+  "artifact.generated",
+  "artifact.indexing_changed",
+  "artifact.published",
+  "artifact.restored",
+  "artifact.revised",
+  "artifact.unpublished"
+];
 
 class ArtifactError extends Error {
   code;
@@ -31,6 +43,38 @@ var defineArtifactRegistry = (definitions) => ({
     return content;
   }
 });
+// src/generators.ts
+var createArtifactGeneratorRegistry = (initial = []) => {
+  const generators = new Map(initial.map((generator) => [generator.kind, generator]));
+  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}`
+      });
+      return artifact;
+    },
+    kinds: () => [...generators.keys()],
+    register: (generator) => {
+      generators.set(generator.kind, generator);
+    }
+  };
+};
 // src/standardKinds.ts
 import { Type } from "@sinclair/typebox";
 var FileArtifactContentSchema = Type.Object({
@@ -135,6 +179,16 @@ var mediaTypeMatches = (accepted, actual) => {
 var createArtifactService = (options) => {
   const now = () => (options.clock ?? (() => new Date))().toISOString();
   const idFactory = options.idFactory ?? (() => crypto.randomUUID());
+  const eventIdFactory = options.eventIdFactory ?? (() => crypto.randomUUID());
+  const event = (artifact, type, payload) => ({
+    artifactId: artifact.id,
+    createdAt: now(),
+    id: eventIdFactory(),
+    ownerId: artifact.ownerId,
+    payload,
+    revision: artifact.revision,
+    type
+  });
   const validateAssets = (kind, assets) => {
     const policy = options.registry.definitions[kind]?.assets;
     if (!policy) {
@@ -152,47 +206,81 @@ var createArtifactService = (options) => {
     }
     return assets;
   };
-  const validateNewAsset = (kind, input, currentCount) => {
+  const validateAssetInputs = (kind, inputs, currentCount = 0) => {
     const policy = options.registry.definitions[kind]?.assets;
-    if (!policy) {
+    if (!policy && inputs.length > 0) {
       throw new ArtifactError("invalid_content", `${kind} artifacts do not accept file assets`);
     }
-    if (policy.maxCount !== undefined && currentCount >= policy.maxCount) {
+    if (policy?.maxCount !== undefined && currentCount + inputs.length > policy.maxCount) {
       throw new ArtifactError("invalid_content", `${kind} artifacts accept at most ${policy.maxCount} file assets`);
     }
-    if (policy.acceptedMediaTypes?.length && !policy.acceptedMediaTypes.some((accepted) => mediaTypeMatches(accepted, input.mediaType))) {
-      throw new ArtifactError("invalid_content", `${input.mediaType} is not accepted by ${kind} artifacts`);
+    const rejected = inputs.find((input) => policy?.acceptedMediaTypes?.length && !policy.acceptedMediaTypes.some((accepted) => mediaTypeMatches(accepted, input.mediaType)));
+    if (rejected) {
+      throw new ArtifactError("invalid_content", `${rejected.mediaType} is not accepted by ${kind} artifacts`);
     }
   };
+  const buildRecord = (ownerId, input, assets) => {
+    const definition = options.registry.definitions[input.kind];
+    if (!definition) {
+      throw new ArtifactError("unknown_kind", `Unknown artifact kind: ${input.kind}`);
+    }
+    const timestamp = now();
+    const artifact = {
+      assets: validateAssets(input.kind, assets),
+      capabilities: definition.capabilities ?? ["archive", "edit", "preview"],
+      content: options.registry.parse(input.kind, input.content),
+      createdAt: timestamp,
+      createdBy: input.createdBy,
+      id: idFactory(),
+      kind: input.kind,
+      metadata: input.metadata ?? {},
+      ownerId,
+      provenance: input.provenance,
+      revision: 1,
+      schemaVersion: definition.schemaVersion ?? 1,
+      status: "draft",
+      title: input.title.trim(),
+      updatedAt: timestamp
+    };
+    return artifact;
+  };
   const get = async (ownerId, artifactId) => {
     const artifact = await options.store.get(ownerId, artifactId);
-    if (!artifact) {
+    if (!artifact)
       throw new ArtifactError("not_found", "Artifact not found");
-    }
     return artifact;
   };
-  const saveRevision = async (artifact, expectedRevision) => {
-    const saved = await options.store.save(artifact, expectedRevision);
+  const saveRevision = async (artifact, expectedRevision, type, payload) => {
+    const saved = await options.store.save(artifact, expectedRevision, [
+      event(artifact, type, payload)
+    ]);
     if (!saved) {
       throw new ArtifactError("conflict", "Artifact changed since it was opened; reload before saving");
     }
     return artifact;
   };
-  return {
+  const requireAssetTransactions = () => {
+    if (!options.assetStore?.stage) {
+      throw new ArtifactError("asset_transaction_unavailable", "The configured artifact asset store does not support atomic bundles");
+    }
+    return options.assetStore;
+  };
+  const service = {
     archive: async (ownerId, artifactId) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "archive");
-      return saveRevision({
+      const archived = {
         ...current,
         revision: current.revision + 1,
         status: "archived",
         updatedAt: now()
-      }, current.revision);
+      };
+      return saveRevision(archived, current.revision, "artifact.archived");
     },
     attach: async (ownerId, artifactId, input, expectedRevision) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "attach");
-      validateNewAsset(current.kind, input, current.assets.length);
+      validateAssetInputs(current.kind, [input], current.assets.length);
       if (!options.assetStore) {
         throw new ArtifactError("asset_store_unavailable", "No artifact asset store is configured");
       }
@@ -200,43 +288,96 @@ var createArtifactService = (options) => {
         artifact: current,
         idempotencyKey: `artifact:${current.id}:asset:${current.revision + 1}`
       });
+      return saveRevision({
+        ...current,
+        assets: validateAssets(current.kind, [...current.assets, reference]),
+        revision: current.revision + 1,
+        updatedAt: now()
+      }, expectedRevision ?? current.revision, "artifact.asset_attached", { assetIds: [reference.id] });
+    },
+    attachBundle: async (ownerId, artifactId, inputs, expectedRevision) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "attach");
+      validateAssetInputs(current.kind, inputs, current.assets.length);
+      const assetStore = requireAssetTransactions();
+      const transaction = await assetStore.stage(inputs, {
+        artifact: current,
+        idempotencyKey: `artifact:${current.id}:bundle:${current.revision + 1}`
+      });
       const assets = validateAssets(current.kind, [
-        ...current.assets.filter((asset) => asset.id !== reference.id),
-        reference
+        ...current.assets,
+        ...transaction.references
       ]);
-      return saveRevision({
+      const revised = {
         ...current,
         assets,
         revision: current.revision + 1,
         updatedAt: now()
-      }, expectedRevision ?? current.revision);
+      };
+      try {
+        await transaction.commit();
+        return await saveRevision(revised, expectedRevision ?? current.revision, "artifact.asset_attached", { assetIds: transaction.references.map((asset) => asset.id) });
+      } catch (error) {
+        await transaction.rollback();
+        throw error;
+      }
+    },
+    collectAssetGarbage: async (input) => {
+      if (!options.assetStore) {
+        throw new ArtifactError("asset_store_unavailable", "No artifact asset store is configured");
+      }
+      const referenced = new Set(await options.store.listReferencedAssetIds());
+      const cutoff = Date.now() - (input.minimumAgeMs ?? 0);
+      const candidates = await options.assetStore.listCandidates();
+      const deleted = [];
+      const retained = [];
+      for (const candidate of candidates) {
+        if (referenced.has(candidate.reference.id) || new Date(candidate.createdAt).getTime() > cutoff) {
+          retained.push(candidate.reference);
+        } else {
+          deleted.push(candidate.reference);
+          if (!input.dryRun)
+            await options.assetStore.delete(candidate.reference);
+        }
+      }
+      return { deleted, retained };
     },
     create: async (ownerId, input) => {
-      const definition = options.registry.definitions[input.kind];
-      if (!definition) {
-        throw new ArtifactError("unknown_kind", `Unknown artifact kind: ${input.kind}`);
+      const artifact = buildRecord(ownerId, input, input.assets ?? []);
+      await options.store.create(artifact, [
+        event(artifact, "artifact.created")
+      ]);
+      return artifact;
+    },
+    createBundle: async (ownerId, input) => {
+      const { assets: assetInputs = [], ...createInput } = input;
+      validateAssetInputs(input.kind, assetInputs);
+      if (assetInputs.length === 0) {
+        return service.create(ownerId, createInput);
       }
-      const content = options.registry.parse(input.kind, input.content);
-      const timestamp = now();
+      const assetStore = requireAssetTransactions();
+      const provisional = buildRecord(ownerId, createInput, []);
+      const transaction = await assetStore.stage(assetInputs, {
+        artifact: provisional,
+        idempotencyKey: `artifact:${provisional.id}:bundle:1`
+      });
       const artifact = {
-        assets: validateAssets(input.kind, input.assets ?? []),
-        capabilities: definition.capabilities ?? ["archive", "edit", "preview"],
-        content,
-        createdAt: timestamp,
-        createdBy: input.createdBy,
-        id: idFactory(),
-        kind: input.kind,
-        metadata: input.metadata ?? {},
-        ownerId,
-        provenance: input.provenance,
-        revision: 1,
-        schemaVersion: definition.schemaVersion ?? 1,
-        status: "draft",
-        title: input.title.trim(),
-        updatedAt: timestamp
+        ...provisional,
+        assets: validateAssets(input.kind, transaction.references)
       };
-      await options.store.create(artifact);
-      return artifact;
+      try {
+        await transaction.commit();
+        await options.store.create(artifact, [
+          event(artifact, "artifact.created"),
+          event(artifact, "artifact.generated", {
+            assetIds: transaction.references.map((asset) => asset.id)
+          })
+        ]);
+        return artifact;
+      } catch (error) {
+        await transaction.rollback();
+        throw error;
+      }
     },
     detach: async (ownerId, artifactId, assetId, expectedRevision) => {
       const current = await get(ownerId, artifactId);
@@ -250,9 +391,10 @@ var createArtifactService = (options) => {
         assets,
         revision: current.revision + 1,
         updatedAt: now()
-      }, expectedRevision ?? current.revision);
+      }, expectedRevision ?? current.revision, "artifact.asset_detached", { assetId });
     },
     get,
+    getIndexingState: (ownerId, artifactId) => options.store.getIndexingState(ownerId, artifactId),
     getRevision: async (ownerId, artifactId, revision) => {
       const snapshot = await options.store.getRevision(ownerId, artifactId, revision);
       if (!snapshot) {
@@ -261,53 +403,66 @@ var createArtifactService = (options) => {
       return snapshot;
     },
     list: (ownerId, query) => options.store.list(ownerId, query),
+    listEvents: (query) => options.store.listEvents(query),
     listRevisions: (ownerId, artifactId) => options.store.listRevisions(ownerId, artifactId),
-    publish: async (ownerId, artifactId) => {
+    markEventProcessed: (eventId, processedAt = now()) => options.store.markEventProcessed(eventId, processedAt),
+    markIndexing: async (ownerId, artifactId, input) => {
+      const artifact = await get(ownerId, artifactId);
+      const state = {
+        artifactId,
+        documentIds: input.documentIds ?? [],
+        error: input.error,
+        indexedAt: input.status === "indexed" ? now() : undefined,
+        revision: input.revision,
+        status: input.status,
+        updatedAt: now()
+      };
+      await options.store.putIndexingState(ownerId, state, [
+        event(artifact, "artifact.indexing_changed", {
+          indexingRevision: state.revision,
+          indexingStatus: state.status
+        })
+      ]);
+      return state;
+    },
+    publish: async (ownerId, artifactId, input = {}) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "publish");
       if (!options.publisher) {
         throw new ArtifactError("publisher_unavailable", "No artifact publisher is configured");
       }
+      const mode = input.mode ?? "pinned";
+      const publishedRevision = current.revision;
       const result = await options.publisher.publish(current, {
-        idempotencyKey: `artifact:${current.id}:publish:${current.revision + 1}`
+        idempotencyKey: `artifact:${current.id}:publish:${publishedRevision}:${mode}`,
+        mode,
+        revision: publishedRevision
       });
       const publishedAt = now();
       const publication = {
         id: result.id,
+        mode,
         publishedAt,
+        revision: publishedRevision,
         url: result.url
       };
-      return saveRevision({
+      const published = {
         ...current,
         publication,
         revision: current.revision + 1,
         status: "published",
         updatedAt: publishedAt
-      }, current.revision);
-    },
-    unpublish: async (ownerId, artifactId) => {
-      const current = await get(ownerId, artifactId);
-      requireCapability(current, "publish");
-      if (!options.publisher) {
-        throw new ArtifactError("publisher_unavailable", "No artifact publisher is configured");
-      }
-      await options.publisher.unpublish(current, {
-        idempotencyKey: `artifact:${current.id}:unpublish:${current.revision + 1}`
+      };
+      return saveRevision(published, current.revision, "artifact.published", {
+        mode,
+        publishedRevision
       });
-      return saveRevision({
-        ...current,
-        publication: undefined,
-        revision: current.revision + 1,
-        status: "draft",
-        updatedAt: now()
-      }, current.revision);
     },
     readAsset: async (ownerId, artifactId, assetId) => {
       const artifact = await get(ownerId, artifactId);
       const asset = artifact.assets.find((candidate) => candidate.id === assetId);
-      if (!asset) {
+      if (!asset)
         throw new ArtifactError("not_found", "Artifact asset not found");
-      }
       if (!options.assetStore) {
         throw new ArtifactError("asset_store_unavailable", "No artifact asset store is configured");
       }
@@ -323,35 +478,54 @@ var createArtifactService = (options) => {
       if (!snapshot) {
         throw new ArtifactError("not_found", "Artifact revision not found");
       }
-      const timestamp = now();
       return saveRevision({
         ...current,
         assets: validateAssets(current.kind, snapshot.assets),
         content: options.registry.parse(current.kind, snapshot.content),
         metadata: snapshot.metadata,
         publication: undefined,
+        provenance: snapshot.provenance,
         revision: current.revision + 1,
         status: "draft",
         title: snapshot.title,
-        updatedAt: timestamp
-      }, expectedRevision ?? current.revision);
+        updatedAt: now()
+      }, expectedRevision ?? current.revision, "artifact.restored", { restoredRevision: revision });
+    },
+    unpublish: async (ownerId, artifactId) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "publish");
+      if (!options.publisher) {
+        throw new ArtifactError("publisher_unavailable", "No artifact publisher is configured");
+      }
+      await options.publisher.unpublish(current, {
+        idempotencyKey: `artifact:${current.id}:unpublish:${current.revision + 1}`
+      });
+      return saveRevision({
+        ...current,
+        publication: undefined,
+        revision: current.revision + 1,
+        status: "draft",
+        updatedAt: now()
+      }, current.revision, "artifact.unpublished");
     },
     update: async (ownerId, artifactId, input) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "edit");
-      const expectedRevision = input.expectedRevision ?? current.revision;
-      const content = input.content === undefined ? current.content : options.registry.parse(current.kind, input.content);
+      const nextRevision = current.revision + 1;
+      const publication = current.publication?.mode === "live" ? { ...current.publication, revision: nextRevision } : current.publication;
       return saveRevision({
         ...current,
         assets: input.assets === undefined ? current.assets : validateAssets(current.kind, input.assets),
-        content,
+        content: input.content === undefined ? current.content : options.registry.parse(current.kind, input.content),
         metadata: input.metadata ?? current.metadata,
-        revision: current.revision + 1,
+        publication,
+        revision: nextRevision,
         title: input.title?.trim() || current.title,
         updatedAt: now()
-      }, expectedRevision);
+      }, input.expectedRevision ?? current.revision, "artifact.revised");
     }
   };
+  return service;
 };
 // src/store.ts
 import { createHash } from "crypto";
@@ -361,6 +535,14 @@ var createMemoryArtifactAssetStore = () => {
   const references = new Map;
   const idempotency = new Map;
   return {
+    delete: async (reference) => {
+      bytes.delete(reference.id);
+      references.delete(reference.id);
+    },
+    listCandidates: async () => [...references.values()].map((reference) => ({
+      createdAt: reference.createdAt,
+      reference: clone(reference)
+    })),
     read: async (reference) => {
       const data = bytes.get(reference.id);
       if (!data)
@@ -377,6 +559,7 @@ var createMemoryArtifactAssetStore = () => {
           algorithm: "sha256",
           value: createHash("sha256").update(input.data).digest("hex")
         },
+        createdAt: new Date().toISOString(),
         id,
         mediaType: input.mediaType,
         metadata: input.metadata,
@@ -389,25 +572,81 @@ var createMemoryArtifactAssetStore = () => {
       references.set(id, clone(reference));
       idempotency.set(context.idempotencyKey, id);
       return reference;
+    },
+    stage: async (inputs, context) => {
+      const staged = inputs.map((input, index) => {
+        const key = `${context.idempotencyKey}:${index}`;
+        const existingId = idempotency.get(key);
+        if (existingId) {
+          return {
+            data: bytes.get(existingId),
+            key,
+            reference: references.get(existingId)
+          };
+        }
+        const id = crypto.randomUUID();
+        const reference = {
+          checksum: {
+            algorithm: "sha256",
+            value: createHash("sha256").update(input.data).digest("hex")
+          },
+          createdAt: new Date().toISOString(),
+          id,
+          mediaType: input.mediaType,
+          metadata: input.metadata,
+          name: input.name,
+          role: input.role ?? "attachment",
+          size: input.data.byteLength,
+          uri: `memory://${id}`
+        };
+        return { data: clone(input.data), key, reference };
+      });
+      return {
+        commit: async () => {
+          for (const item of staged) {
+            bytes.set(item.reference.id, clone(item.data));
+            references.set(item.reference.id, clone(item.reference));
+            idempotency.set(item.key, item.reference.id);
+          }
+        },
+        references: staged.map((item) => clone(item.reference)),
+        rollback: async () => {
+          for (const item of staged) {
+            bytes.delete(item.reference.id);
+            references.delete(item.reference.id);
+            idempotency.delete(item.key);
+          }
+        }
+      };
     }
   };
 };
 var createMemoryArtifactStore = (initial = []) => {
   const records = new Map(initial.map((record) => [record.id, clone(record)]));
   const revisions = new Map;
+  const events = new Map;
+  const indexing = new Map;
   for (const record of initial)
     revisions.set(record.id, [clone(record)]);
   return {
-    create: async (record) => {
+    create: async (record, newEvents = []) => {
       if (records.has(record.id))
         throw new Error(`Duplicate artifact id: ${record.id}`);
       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;
     },
+    getIndexingState: async (ownerId, artifactId) => {
+      const record = records.get(artifactId);
+      if (record?.ownerId !== ownerId)
+        return null;
+      return clone(indexing.get(artifactId) ?? null);
+    },
     getRevision: async (ownerId, artifactId, revision) => {
       const current = records.get(artifactId);
       if (current?.ownerId !== ownerId)
@@ -421,7 +660,27 @@ var createMemoryArtifactStore = (initial = []) => {
         return [];
       return (revisions.get(artifactId) ?? []).toSorted((left, right) => right.revision - left.revision).map(clone);
     },
-    save: async (record, expectedRevision) => {
+    listEvents: async (query = {}) => [...events.values()].filter((event) => (query.processed === undefined || Boolean(event.processedAt) === query.processed) && (!query.type || event.type === query.type)).sort((left, right) => left.createdAt.localeCompare(right.createdAt)).slice(0, query.limit ?? Number.POSITIVE_INFINITY).map(clone),
+    listReferencedAssetIds: async () => [
+      ...new Set([...revisions.values()].flat().flatMap((revision) => revision.assets.map((asset) => asset.id)))
+    ],
+    markEventProcessed: async (eventId, processedAt) => {
+      const event = events.get(eventId);
+      if (!event)
+        return false;
+      events.set(eventId, { ...event, processedAt });
+      return true;
+    },
+    putIndexingState: async (ownerId, state, newEvents = []) => {
+      const record = records.get(state.artifactId);
+      if (record?.ownerId !== ownerId) {
+        throw new Error("Artifact not found");
+      }
+      indexing.set(state.artifactId, clone(state));
+      for (const event of newEvents)
+        events.set(event.id, clone(event));
+    },
+    save: async (record, expectedRevision, newEvents = []) => {
       const current = records.get(record.id);
       if (!current || current.ownerId !== record.ownerId || current.revision !== expectedRevision) {
         return false;
@@ -431,6 +690,8 @@ var createMemoryArtifactStore = (initial = []) => {
         ...revisions.get(record.id) ?? [],
         clone(record)
       ]);
+      for (const event of newEvents)
+        events.set(event.id, clone(event));
       return true;
     }
   };
@@ -509,11 +770,14 @@ var createArtifactTools = (options) => ({
       if (!artifactId || typeof input.published !== "boolean") {
         return "Provide artifactId and published.";
       }
-      const artifact = input.published ? await options.service.publish(options.ownerId, artifactId) : await options.service.unpublish(options.ownerId, artifactId);
+      const artifact = input.published ? await options.service.publish(options.ownerId, artifactId, {
+        mode: input.mode === "live" ? "live" : "pinned"
+      }) : await options.service.unpublish(options.ownerId, artifactId);
       return JSON.stringify(artifact);
     },
     input: Type2.Object({
       artifactId: Type2.String({ minLength: 1 }),
+      mode: Type2.Optional(Type2.Union([Type2.Literal("live"), Type2.Literal("pinned")])),
       published: Type2.Boolean()
     })
   },
@@ -563,7 +827,9 @@ export {
   createArtifactTools,
   createArtifactService,
   createArtifactRendererRegistry,
+  createArtifactGeneratorRegistry,
   STANDARD_ARTIFACT_KIND_NAMES,
   ArtifactError,
-  ARTIFACT_STATUSES
+  ARTIFACT_STATUSES,
+  ARTIFACT_EVENT_TYPES
 };

package/dist/rag.js

@@ -39,6 +39,42 @@ var artifactToRAGUploads = async (artifact, reader, options = {}) => {
     ...uploads
   ];
 };
+var createArtifactRAGIndexCoordinator = (options) => ({
+  index: async (artifact) => {
+    const previous = await options.service.getIndexingState(artifact.ownerId, artifact.id);
+    await options.service.markIndexing(artifact.ownerId, artifact.id, {
+      documentIds: previous?.documentIds,
+      revision: artifact.revision,
+      status: "pending"
+    });
+    try {
+      const uploads = await artifactToRAGUploads(artifact, options.reader);
+      const indexed = await options.target.index(uploads, { artifact });
+      if (previous?.documentIds.length && options.target.remove) {
+        const currentIds = new Set(indexed.documentIds);
+        const obsoleteIds = previous.documentIds.filter((documentId) => !currentIds.has(documentId));
+        if (obsoleteIds.length) {
+          await options.target.remove(obsoleteIds, { artifact });
+        }
+      }
+      await options.service.markIndexing(artifact.ownerId, artifact.id, {
+        documentIds: indexed.documentIds,
+        revision: artifact.revision,
+        status: "indexed"
+      });
+      return indexed;
+    } catch (error) {
+      await options.service.markIndexing(artifact.ownerId, artifact.id, {
+        documentIds: previous?.documentIds,
+        error: error instanceof Error ? error.message : String(error),
+        revision: artifact.revision,
+        status: "failed"
+      });
+      throw error;
+    }
+  }
+});
 export {
+  createArtifactRAGIndexCoordinator,
   artifactToRAGUploads
 };

package/dist/src/generators.d.ts

@@ -0,0 +1,34 @@
+import type { ArtifactAssetWriteInput, ArtifactBundleCreateInput, ArtifactProvenance, ArtifactRecord } from "./types";
+export type ArtifactGenerationInput = {
+    createdBy: string;
+    input?: Record<string, unknown>;
+    kind: string;
+    ownerId: string;
+    prompt?: string;
+    title?: string;
+};
+export type ArtifactGenerationContext = {
+    ownerId: string;
+};
+export type ArtifactGenerationResult = {
+    assets?: ArtifactAssetWriteInput[];
+    content: unknown;
+    metadata?: Record<string, unknown>;
+    provenance?: ArtifactProvenance;
+    title?: string;
+    warnings?: string[];
+};
+export type ArtifactGenerator = {
+    generate(input: ArtifactGenerationInput, context: ArtifactGenerationContext): Promise<ArtifactGenerationResult>;
+    kind: string;
+    name: string;
+};
+export type ArtifactBundleCreator = {
+    createBundle(ownerId: string, input: ArtifactBundleCreateInput): Promise<ArtifactRecord>;
+};
+export declare const createArtifactGeneratorRegistry: (initial?: ArtifactGenerator[]) => {
+    generate: (service: ArtifactBundleCreator, input: ArtifactGenerationInput) => Promise<ArtifactRecord>;
+    kinds: () => string[];
+    register: (generator: ArtifactGenerator) => void;
+};
+export type ArtifactGeneratorRegistry = ReturnType<typeof createArtifactGeneratorRegistry>;

package/dist/src/index.d.ts

@@ -7,9 +7,10 @@
  * retains authorization, persistence, URLs, UI, and delivery policy.
  */
 export { defineArtifactRegistry, type ArtifactContent, type ArtifactKindDefinition, type ArtifactKindDefinitions, type ArtifactRegistry, } from "./registry";
+export { createArtifactGeneratorRegistry, type ArtifactBundleCreator, type ArtifactGenerationContext, type ArtifactGenerationInput, type ArtifactGenerationResult, type ArtifactGenerator, type ArtifactGeneratorRegistry, } from "./generators";
 export { STANDARD_ARTIFACT_KIND_NAMES, standardArtifactDefinitions, } from "./standardKinds";
 export { createArtifactRendererRegistry, type ArtifactRenderer, type ArtifactRendererRegistry, type ArtifactRenderResult, } from "./renderers";
 export { createArtifactService, type ArtifactPublisher, type ArtifactService, type ArtifactServiceOptions, } from "./service";
-export { createMemoryArtifactStore, createMemoryArtifactAssetStore, type ArtifactAssetStore, type ArtifactStore, } from "./store";
+export { createMemoryArtifactStore, createMemoryArtifactAssetStore, type ArtifactAssetStore, type ArtifactAssetTransaction, type ArtifactStore, } from "./store";
 export { createArtifactTools, type ArtifactToolDefinition, type ArtifactToolMap, type ArtifactToolOptions, } from "./tools";
-export { ARTIFACT_STATUSES, ArtifactError, type ArtifactAssetReference, type ArtifactAssetRole, type ArtifactAssetWriteInput, type ArtifactCapability, type ArtifactCreateInput, type ArtifactErrorCode, type ArtifactListQuery, type ArtifactProvenance, type ArtifactPublication, type ArtifactRecord, type ArtifactRevision, type ArtifactStatus, type ArtifactUpdateInput, } from "./types";
+export { ARTIFACT_STATUSES, ARTIFACT_EVENT_TYPES, ArtifactError, 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, } from "./types";

package/dist/src/manifest.d.ts

@@ -1,18 +1,33 @@
 export declare const manifest: import("@absolutejs/manifest").PackageManifest<Record<string, never>, {
     archive: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
     attach: (ownerId: string, artifactId: string, input: import("./types").ArtifactAssetWriteInput, expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
+    attachBundle: (ownerId: string, artifactId: string, inputs: import("./types").ArtifactAssetWriteInput[], expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
+    collectAssetGarbage: (input: {
+        dryRun?: boolean;
+        minimumAgeMs?: number;
+    }) => 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>;
     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>;
     getRevision: (ownerId: string, artifactId: string, revision: number) => Promise<Readonly<import("./types").ArtifactRecord<unknown>>>;
     list: (ownerId: string, query?: import("./types").ArtifactListQuery) => Promise<import("./types").ArtifactRecord[]>;
+    listEvents: (query?: import("./types").ArtifactEventQuery) => Promise<import("./types").ArtifactEvent[]>;
     listRevisions: (ownerId: string, artifactId: string) => Promise<Readonly<import("./types").ArtifactRecord<unknown>>[]>;
-    publish: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
-    unpublish: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
+    markEventProcessed: (eventId: string, processedAt?: string) => Promise<boolean>;
+    markIndexing: (ownerId: string, artifactId: string, input: {
+        documentIds?: string[];
+        error?: string;
+        revision: number;
+        status: import("./types").ArtifactIndexingStatus;
+    }) => Promise<import("./types").ArtifactIndexingState>;
+    publish: (ownerId: string, artifactId: string, input?: import("./types").ArtifactPublishInput) => Promise<import("./types").ArtifactRecord>;
     readAsset: (ownerId: string, artifactId: string, assetId: string) => Promise<{
         asset: import("./types").ArtifactAssetReference;
         data: Uint8Array<ArrayBufferLike>;
     }>;
     restore: (ownerId: string, artifactId: string, revision: number, expectedRevision?: number) => Promise<import("./types").ArtifactRecord>;
+    unpublish: (ownerId: string, artifactId: string) => Promise<import("./types").ArtifactRecord>;
     update: (ownerId: string, artifactId: string, input: import("./types").ArtifactUpdateInput) => Promise<import("./types").ArtifactRecord>;
 }>;

package/dist/src/rag.d.ts

@@ -8,8 +8,39 @@ export type ArtifactRAGAssetReader = {
 export type ArtifactRAGUploadOptions = {
     includeStructuredContent?: boolean;
 };
+export type ArtifactRAGIndexTarget = {
+    index(uploads: RAGDocumentUploadInput[], context: {
+        artifact: ArtifactRecord;
+    }): Promise<{
+        documentIds: string[];
+    }>;
+    remove?(documentIds: string[], context: {
+        artifact: ArtifactRecord;
+    }): Promise<void>;
+};
+export type ArtifactRAGIndexStateWriter = {
+    getIndexingState(ownerId: string, artifactId: string): Promise<{
+        documentIds: string[];
+    } | null>;
+    markIndexing(ownerId: string, artifactId: string, input: {
+        documentIds?: string[];
+        error?: string;
+        revision: number;
+        status: "failed" | "indexed" | "pending" | "stale";
+    }): Promise<unknown>;
+};
 /**
  * Resolve an artifact revision into upload inputs accepted by @absolutejs/rag.
  * Storage URIs remain opaque; only the supplied reader is allowed to access bytes.
  */
 export declare const artifactToRAGUploads: (artifact: ArtifactRecord, reader: ArtifactRAGAssetReader, options?: ArtifactRAGUploadOptions) => Promise<RAGDocumentUploadInput[]>;
+export declare const createArtifactRAGIndexCoordinator: (options: {
+    reader: ArtifactRAGAssetReader;
+    service: ArtifactRAGIndexStateWriter;
+    target: ArtifactRAGIndexTarget;
+}) => {
+    index: (artifact: ArtifactRecord) => Promise<{
+        documentIds: string[];
+    }>;
+};
+export type ArtifactRAGIndexCoordinator = ReturnType<typeof createArtifactRAGIndexCoordinator>;

package/dist/src/service.d.ts

@@ -1,9 +1,11 @@
 import type { ArtifactKindDefinitions, ArtifactRegistry } from "./registry";
 import type { ArtifactAssetStore, ArtifactStore } from "./store";
-import { type ArtifactAssetReference, type ArtifactAssetWriteInput, type ArtifactCreateInput, type ArtifactListQuery, type ArtifactRecord, type ArtifactUpdateInput } from "./types";
+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";
 export type ArtifactPublisher = {
     publish(artifact: ArtifactRecord, options: {
         idempotencyKey: string;
+        mode: "live" | "pinned";
+        revision: number;
     }): Promise<{
         id: string;
         url: string;
@@ -15,6 +17,7 @@ export type ArtifactPublisher = {
 export type ArtifactServiceOptions<TDefinitions extends ArtifactKindDefinitions = ArtifactKindDefinitions> = {
     assetStore?: ArtifactAssetStore;
     clock?: () => Date;
+    eventIdFactory?: () => string;
     idFactory?: () => string;
     publisher?: ArtifactPublisher;
     registry: ArtifactRegistry<TDefinitions>;
@@ -24,18 +27,33 @@ export type ArtifactService = ReturnType<typeof createArtifactService>;
 export declare const createArtifactService: <TDefinitions extends ArtifactKindDefinitions>(options: ArtifactServiceOptions<TDefinitions>) => {
     archive: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
     attach: (ownerId: string, artifactId: string, input: ArtifactAssetWriteInput, expectedRevision?: number) => Promise<ArtifactRecord>;
+    attachBundle: (ownerId: string, artifactId: string, inputs: ArtifactAssetWriteInput[], expectedRevision?: number) => Promise<ArtifactRecord>;
+    collectAssetGarbage: (input: {
+        dryRun?: boolean;
+        minimumAgeMs?: number;
+    }) => Promise<ArtifactGarbageCollectionResult>;
     create: (ownerId: string, input: ArtifactCreateInput) => Promise<ArtifactRecord>;
+    createBundle: (ownerId: string, input: ArtifactBundleCreateInput) => Promise<ArtifactRecord>;
     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>;
     getRevision: (ownerId: string, artifactId: string, revision: number) => Promise<Readonly<ArtifactRecord<unknown>>>;
     list: (ownerId: string, query?: ArtifactListQuery) => Promise<ArtifactRecord[]>;
+    listEvents: (query?: ArtifactEventQuery) => Promise<ArtifactEvent[]>;
     listRevisions: (ownerId: string, artifactId: string) => Promise<Readonly<ArtifactRecord<unknown>>[]>;
-    publish: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
-    unpublish: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
+    markEventProcessed: (eventId: string, processedAt?: string) => Promise<boolean>;
+    markIndexing: (ownerId: string, artifactId: string, input: {
+        documentIds?: string[];
+        error?: string;
+        revision: number;
+        status: ArtifactIndexingStatus;
+    }) => Promise<ArtifactIndexingState>;
+    publish: (ownerId: string, artifactId: string, input?: ArtifactPublishInput) => Promise<ArtifactRecord>;
     readAsset: (ownerId: string, artifactId: string, assetId: string) => Promise<{
         asset: ArtifactAssetReference;
         data: Uint8Array<ArrayBufferLike>;
     }>;
     restore: (ownerId: string, artifactId: string, revision: number, expectedRevision?: number) => Promise<ArtifactRecord>;
+    unpublish: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
     update: (ownerId: string, artifactId: string, input: ArtifactUpdateInput) => Promise<ArtifactRecord>;
 };

package/dist/src/store.d.ts

@@ -1,5 +1,12 @@
-import type { ArtifactAssetReference, ArtifactAssetWriteInput, ArtifactListQuery, ArtifactRecord, ArtifactRevision } from "./types";
+import type { ArtifactAssetReference, ArtifactAssetWriteInput, ArtifactEvent, ArtifactEventQuery, ArtifactIndexingState, ArtifactListQuery, ArtifactRecord, ArtifactRevision, ArtifactRetentionCandidate } from "./types";
+export type ArtifactAssetTransaction = {
+    commit(): Promise<void>;
+    references: ArtifactAssetReference[];
+    rollback(): Promise<void>;
+};
 export type ArtifactAssetStore = {
+    delete(reference: ArtifactAssetReference): Promise<void>;
+    listCandidates(): Promise<ArtifactRetentionCandidate[]>;
     read(reference: ArtifactAssetReference, context: {
         artifact: ArtifactRecord;
     }): Promise<Uint8Array>;
@@ -7,16 +14,25 @@ export type ArtifactAssetStore = {
         artifact: ArtifactRecord;
         idempotencyKey: string;
     }): Promise<ArtifactAssetReference>;
+    stage?(inputs: ArtifactAssetWriteInput[], context: {
+        artifact: ArtifactRecord;
+        idempotencyKey: string;
+    }): Promise<ArtifactAssetTransaction>;
 };
 export type ArtifactStore = {
     /** Persist the current record and its first immutable revision atomically. */
-    create(record: ArtifactRecord): Promise<void>;
+    create(record: ArtifactRecord, events?: ArtifactEvent[]): 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>;
     list(ownerId: string, query?: ArtifactListQuery): Promise<ArtifactRecord[]>;
     listRevisions(ownerId: string, artifactId: string): Promise<ArtifactRevision[]>;
+    listEvents(query?: ArtifactEventQuery): Promise<ArtifactEvent[]>;
+    listReferencedAssetIds(): Promise<string[]>;
+    markEventProcessed(eventId: string, processedAt: string): Promise<boolean>;
+    putIndexingState(ownerId: string, state: ArtifactIndexingState, events?: ArtifactEvent[]): Promise<void>;
     /** Compare, replace current state, and append its revision atomically. */
-    save(record: ArtifactRecord, expectedRevision: number): Promise<boolean>;
+    save(record: ArtifactRecord, expectedRevision: number, events?: ArtifactEvent[]): Promise<boolean>;
 };
 export declare const createMemoryArtifactAssetStore: () => ArtifactAssetStore;
 export declare const createMemoryArtifactStore: (initial?: ArtifactRecord[]) => ArtifactStore;

package/dist/src/types.d.ts

@@ -2,14 +2,24 @@ export declare const ARTIFACT_STATUSES: readonly ["draft", "published", "archive
 export type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];
 export type ArtifactCapability = "attach" | "archive" | "edit" | "export" | "preview" | "publish" | "refine";
 export type ArtifactProvenance = {
+    lineage?: ArtifactLineageReference[];
     model?: string;
     sourceIds?: string[];
     tool?: string;
     traceId?: string;
 };
+export type ArtifactLineageRelation = "derived_from" | "generated_from" | "references" | "replaces";
+export type ArtifactLineageReference = {
+    artifactId?: string;
+    relation: ArtifactLineageRelation;
+    revision?: number;
+    sourceId?: string;
+};
 export type ArtifactPublication = {
     id: string;
+    mode: "live" | "pinned";
     publishedAt: string;
+    revision: number;
     url: string;
 };
 export type ArtifactAssetRole = "attachment" | "primary" | "preview" | "source";
@@ -19,6 +29,7 @@ export type ArtifactAssetReference = {
         value: string;
     };
     id: string;
+    createdAt: string;
     mediaType: string;
     metadata?: Record<string, unknown>;
     name: string;
@@ -52,6 +63,33 @@ export type ArtifactRecord<TContent = unknown> = {
     title: string;
     updatedAt: string;
 };
+export declare const ARTIFACT_EVENT_TYPES: readonly ["artifact.archived", "artifact.asset_attached", "artifact.asset_detached", "artifact.created", "artifact.generated", "artifact.indexing_changed", "artifact.published", "artifact.restored", "artifact.revised", "artifact.unpublished"];
+export type ArtifactEventType = (typeof ARTIFACT_EVENT_TYPES)[number];
+export type ArtifactEvent = {
+    artifactId: string;
+    createdAt: string;
+    id: string;
+    ownerId: string;
+    payload?: Record<string, unknown>;
+    processedAt?: string;
+    revision: number;
+    type: ArtifactEventType;
+};
+export type ArtifactEventQuery = {
+    limit?: number;
+    processed?: boolean;
+    type?: ArtifactEventType;
+};
+export type ArtifactIndexingStatus = "failed" | "indexed" | "pending" | "stale";
+export type ArtifactIndexingState = {
+    artifactId: string;
+    documentIds: string[];
+    error?: string;
+    indexedAt?: string;
+    revision: number;
+    status: ArtifactIndexingStatus;
+    updatedAt: string;
+};
 /** An immutable point-in-time copy of an artifact record. */
 export type ArtifactRevision<TContent = unknown> = Readonly<ArtifactRecord<TContent>>;
 export type ArtifactListQuery = {
@@ -75,7 +113,21 @@ export type ArtifactUpdateInput = {
     metadata?: Record<string, unknown>;
     title?: string;
 };
-export type ArtifactErrorCode = "asset_store_unavailable" | "conflict" | "invalid_content" | "not_found" | "publisher_unavailable" | "renderer_unavailable" | "unsupported_capability" | "unknown_kind";
+export type ArtifactBundleCreateInput = Omit<ArtifactCreateInput, "assets"> & {
+    assets?: ArtifactAssetWriteInput[];
+};
+export type ArtifactPublishInput = {
+    mode?: "live" | "pinned";
+};
+export type ArtifactRetentionCandidate = {
+    createdAt: string;
+    reference: ArtifactAssetReference;
+};
+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 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.0.2",
+  "version": "0.0.4",
   "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",