@absolutejs/artifacts 0.0.1 → 0.0.2

package/README.md

@@ -14,11 +14,15 @@ routes, authorization, UI, or hosting.
 
 - Structured artifact-kind schemas and runtime validation
 - Draft, published, and archived lifecycle states
-- Optimistic revisions that prevent lost edits
-- Storage, renderer, and publisher interfaces
-- An in-memory store for development and tests
+- Immutable revision history, restoration, and optimistic updates
+- Structured content plus opaque references to generated or source files
+- Artifact, asset, renderer, and publisher storage interfaces
+- In-memory artifact and asset stores for development and tests
 - Owner-bound lifecycle tools structurally compatible with AI tool maps
 - Provenance fields for model, tool, trace, and source entities
+- 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
 
 Your application retains authorization, durable persistence, public tokens,
 URLs, notifications, analytics, submissions, and product-specific rendering.
@@ -29,6 +33,7 @@ URLs, notifications, analytics, submissions, and product-specific rendering.
 import { Type } from "@sinclair/typebox";
 import {
   createArtifactService,
+  createMemoryArtifactAssetStore,
   createMemoryArtifactStore,
   defineArtifactRegistry,
 } from "@absolutejs/artifacts";
@@ -51,6 +56,7 @@ const registry = defineArtifactRegistry({
 });
 
 const artifacts = createArtifactService({
+  assetStore: createMemoryArtifactAssetStore(),
   registry,
   store: createMemoryArtifactStore(),
 });
@@ -67,6 +73,70 @@ const page = await artifacts.create("owner-123", {
 });
 ```
 
+Every successful create or lifecycle mutation appends an immutable snapshot.
+Restoring history creates a new private draft instead of rewriting or
+republishing an old revision:
+
+```ts
+const history = await artifacts.listRevisions("owner-123", page.id);
+const restored = await artifacts.restore("owner-123", page.id, 1);
+```
+
+## File-backed artifact kinds
+
+Use the bundled definitions directly or compose them with application-specific
+kinds:
+
+```ts
+import {
+  defineArtifactRegistry,
+  standardArtifactDefinitions,
+} from "@absolutejs/artifacts";
+
+const registry = defineArtifactRegistry({
+  ...standardArtifactDefinitions,
+  page: myPageDefinition,
+});
+```
+
+File bytes stay in host storage. Artifact records retain opaque references with
+name, media type, size, checksum, role, and storage URI. The URI is not treated
+as a public URL and the package reads it only through the configured asset
+store. Detaching a file does not delete its bytes because older immutable
+revisions may still reference it.
+
+```ts
+const report = await artifacts.create("owner-123", {
+  content: { summary: "Quarterly results" },
+  createdBy: "agent",
+  kind: "document",
+  title: "Q3 report",
+});
+
+await artifacts.attach("owner-123", report.id, {
+  data: pdfBytes,
+  mediaType: "application/pdf",
+  name: "q3-report.pdf",
+  role: "primary",
+});
+```
+
+## RAG ingestion
+
+The optional `@absolutejs/artifacts/rag` entry point resolves one current or
+historical artifact record into the upload contract already accepted by
+`@absolutejs/rag`. Structured content is included as JSON and every attached
+file is included without exposing its storage URI:
+
+```ts
+import { artifactToRAGUploads } from "@absolutejs/artifacts/rag";
+import { buildRAGUpsertInputFromUploads } from "@absolutejs/rag";
+
+const revision = await artifacts.getRevision("owner-123", report.id, 2);
+const uploads = await artifactToRAGUploads(revision, assetStore);
+const upsert = await buildRAGUpsertInputFromUploads({ uploads });
+```
+
 ## Compose publishing and rendering
 
 Publishing is an adapter because public access is a host policy:

package/dist/index.js

@@ -31,6 +31,76 @@ var defineArtifactRegistry = (definitions) => ({
     return content;
   }
 });
+// src/standardKinds.ts
+import { Type } from "@sinclair/typebox";
+var FileArtifactContentSchema = Type.Object({
+  description: Type.Optional(Type.String()),
+  instructions: Type.Optional(Type.String()),
+  summary: Type.Optional(Type.String())
+});
+var capabilities = [
+  "attach",
+  "archive",
+  "edit",
+  "export",
+  "preview",
+  "refine"
+];
+var fileKind = (label, acceptedMediaTypes, maxCount = 1) => ({
+  assets: { acceptedMediaTypes, maxCount },
+  capabilities: [...capabilities],
+  content: FileArtifactContentSchema,
+  label,
+  schemaVersion: 1
+});
+var standardArtifactDefinitions = {
+  archive: fileKind("Archive", [
+    "application/gzip",
+    "application/vnd.rar",
+    "application/x-7z-compressed",
+    "application/x-bzip2",
+    "application/x-tar",
+    "application/zip"
+  ], 20),
+  audio: fileKind("Audio", ["audio/*"]),
+  code: fileKind("Code", ["application/json", "application/xml", "text/*"], 100),
+  dataset: fileKind("Dataset", [
+    "application/json",
+    "application/x-ndjson",
+    "application/xml",
+    "text/csv",
+    "text/tab-separated-values",
+    "text/plain",
+    "text/yaml"
+  ], 20),
+  document: fileKind("Document", [
+    "application/epub+zip",
+    "application/msword",
+    "application/pdf",
+    "application/rtf",
+    "application/vnd.oasis.opendocument.text",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "text/*"
+  ], 20),
+  email: fileKind("Email", ["application/mbox", "application/vnd.ms-outlook", "message/*", "text/*"], 100),
+  file: fileKind("File", ["*/*"], 100),
+  image: fileKind("Image", ["image/*"], 20),
+  presentation: fileKind("Presentation", [
+    "application/pdf",
+    "application/vnd.ms-powerpoint",
+    "application/vnd.oasis.opendocument.presentation",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+  ], 20),
+  spreadsheet: fileKind("Spreadsheet", [
+    "application/vnd.ms-excel",
+    "application/vnd.oasis.opendocument.spreadsheet",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "text/csv",
+    "text/tab-separated-values"
+  ], 20),
+  video: fileKind("Video", ["video/*"])
+};
+var STANDARD_ARTIFACT_KIND_NAMES = Object.keys(standardArtifactDefinitions);
 // src/renderers.ts
 var createArtifactRendererRegistry = (initial = []) => {
   const key = (kind, format) => `${kind}:${format}`;
@@ -55,9 +125,45 @@ var requireCapability = (artifact, capability) => {
     throw new ArtifactError("unsupported_capability", `${artifact.kind} artifacts do not support ${capability}`);
   }
 };
+var mediaTypeMatches = (accepted, actual) => {
+  if (accepted === "*/*" || accepted === actual)
+    return true;
+  if (!accepted.endsWith("/*"))
+    return false;
+  return actual.startsWith(accepted.slice(0, -1));
+};
 var createArtifactService = (options) => {
   const now = () => (options.clock ?? (() => new Date))().toISOString();
   const idFactory = options.idFactory ?? (() => crypto.randomUUID());
+  const validateAssets = (kind, assets) => {
+    const policy = options.registry.definitions[kind]?.assets;
+    if (!policy) {
+      if (assets.length > 0) {
+        throw new ArtifactError("invalid_content", `${kind} artifacts do not accept file assets`);
+      }
+      return assets;
+    }
+    if (policy.maxCount !== undefined && assets.length > policy.maxCount) {
+      throw new ArtifactError("invalid_content", `${kind} artifacts accept at most ${policy.maxCount} file assets`);
+    }
+    const rejected = assets.find((asset) => policy.acceptedMediaTypes?.length && !policy.acceptedMediaTypes.some((accepted) => mediaTypeMatches(accepted, asset.mediaType)));
+    if (rejected) {
+      throw new ArtifactError("invalid_content", `${rejected.mediaType} is not accepted by ${kind} artifacts`);
+    }
+    return assets;
+  };
+  const validateNewAsset = (kind, input, currentCount) => {
+    const policy = options.registry.definitions[kind]?.assets;
+    if (!policy) {
+      throw new ArtifactError("invalid_content", `${kind} artifacts do not accept file assets`);
+    }
+    if (policy.maxCount !== undefined && currentCount >= 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 get = async (ownerId, artifactId) => {
     const artifact = await options.store.get(ownerId, artifactId);
     if (!artifact) {
@@ -83,6 +189,28 @@ var createArtifactService = (options) => {
         updatedAt: now()
       }, current.revision);
     },
+    attach: async (ownerId, artifactId, input, expectedRevision) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "attach");
+      validateNewAsset(current.kind, input, current.assets.length);
+      if (!options.assetStore) {
+        throw new ArtifactError("asset_store_unavailable", "No artifact asset store is configured");
+      }
+      const reference = await options.assetStore.write(input, {
+        artifact: current,
+        idempotencyKey: `artifact:${current.id}:asset:${current.revision + 1}`
+      });
+      const assets = validateAssets(current.kind, [
+        ...current.assets.filter((asset) => asset.id !== reference.id),
+        reference
+      ]);
+      return saveRevision({
+        ...current,
+        assets,
+        revision: current.revision + 1,
+        updatedAt: now()
+      }, expectedRevision ?? current.revision);
+    },
     create: async (ownerId, input) => {
       const definition = options.registry.definitions[input.kind];
       if (!definition) {
@@ -91,6 +219,7 @@ var createArtifactService = (options) => {
       const content = options.registry.parse(input.kind, input.content);
       const timestamp = now();
       const artifact = {
+        assets: validateAssets(input.kind, input.assets ?? []),
         capabilities: definition.capabilities ?? ["archive", "edit", "preview"],
         content,
         createdAt: timestamp,
@@ -109,8 +238,30 @@ var createArtifactService = (options) => {
       await options.store.create(artifact);
       return artifact;
     },
+    detach: async (ownerId, artifactId, assetId, expectedRevision) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "attach");
+      const assets = current.assets.filter((asset) => asset.id !== assetId);
+      if (assets.length === current.assets.length) {
+        throw new ArtifactError("not_found", "Artifact asset not found");
+      }
+      return saveRevision({
+        ...current,
+        assets,
+        revision: current.revision + 1,
+        updatedAt: now()
+      }, expectedRevision ?? current.revision);
+    },
     get,
+    getRevision: async (ownerId, artifactId, revision) => {
+      const snapshot = await options.store.getRevision(ownerId, artifactId, revision);
+      if (!snapshot) {
+        throw new ArtifactError("not_found", "Artifact revision not found");
+      }
+      return snapshot;
+    },
     list: (ownerId, query) => options.store.list(ownerId, query),
+    listRevisions: (ownerId, artifactId) => options.store.listRevisions(ownerId, artifactId),
     publish: async (ownerId, artifactId) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "publish");
@@ -151,6 +302,40 @@ var createArtifactService = (options) => {
         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) {
+        throw new ArtifactError("not_found", "Artifact asset not found");
+      }
+      if (!options.assetStore) {
+        throw new ArtifactError("asset_store_unavailable", "No artifact asset store is configured");
+      }
+      return {
+        asset,
+        data: await options.assetStore.read(asset, { artifact })
+      };
+    },
+    restore: async (ownerId, artifactId, revision, expectedRevision) => {
+      const current = await get(ownerId, artifactId);
+      requireCapability(current, "edit");
+      const snapshot = await options.store.getRevision(ownerId, artifactId, revision);
+      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,
+        revision: current.revision + 1,
+        status: "draft",
+        title: snapshot.title,
+        updatedAt: timestamp
+      }, expectedRevision ?? current.revision);
+    },
     update: async (ownerId, artifactId, input) => {
       const current = await get(ownerId, artifactId);
       requireCapability(current, "edit");
@@ -158,6 +343,7 @@ var createArtifactService = (options) => {
       const content = input.content === undefined ? current.content : options.registry.parse(current.kind, input.content);
       return saveRevision({
         ...current,
+        assets: input.assets === undefined ? current.assets : validateAssets(current.kind, input.assets),
         content,
         metadata: input.metadata ?? current.metadata,
         revision: current.revision + 1,
@@ -168,32 +354,89 @@ var createArtifactService = (options) => {
   };
 };
 // src/store.ts
+import { createHash } from "crypto";
 var clone = (value) => structuredClone(value);
+var createMemoryArtifactAssetStore = () => {
+  const bytes = new Map;
+  const references = new Map;
+  const idempotency = new Map;
+  return {
+    read: async (reference) => {
+      const data = bytes.get(reference.id);
+      if (!data)
+        throw new Error(`Artifact asset not found: ${reference.id}`);
+      return clone(data);
+    },
+    write: async (input, context) => {
+      const existingId = idempotency.get(context.idempotencyKey);
+      if (existingId)
+        return clone(references.get(existingId));
+      const id = crypto.randomUUID();
+      const reference = {
+        checksum: {
+          algorithm: "sha256",
+          value: createHash("sha256").update(input.data).digest("hex")
+        },
+        id,
+        mediaType: input.mediaType,
+        metadata: input.metadata,
+        name: input.name,
+        role: input.role ?? "attachment",
+        size: input.data.byteLength,
+        uri: `memory://${id}`
+      };
+      bytes.set(id, clone(input.data));
+      references.set(id, clone(reference));
+      idempotency.set(context.idempotencyKey, id);
+      return reference;
+    }
+  };
+};
 var createMemoryArtifactStore = (initial = []) => {
   const records = new Map(initial.map((record) => [record.id, clone(record)]));
+  const revisions = new Map;
+  for (const record of initial)
+    revisions.set(record.id, [clone(record)]);
   return {
     create: async (record) => {
       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)]);
     },
     get: async (ownerId, artifactId) => {
       const record = records.get(artifactId);
       return record?.ownerId === ownerId ? clone(record) : null;
     },
+    getRevision: async (ownerId, artifactId, revision) => {
+      const current = records.get(artifactId);
+      if (current?.ownerId !== ownerId)
+        return null;
+      return clone(revisions.get(artifactId)?.find((candidate) => candidate.revision === revision) ?? null);
+    },
     list: async (ownerId, query = {}) => [...records.values()].filter((record) => record.ownerId === ownerId && (!query.kind || record.kind === query.kind) && (!query.status || record.status === query.status)).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)).slice(0, query.limit ?? Number.POSITIVE_INFINITY).map(clone),
+    listRevisions: async (ownerId, artifactId) => {
+      const current = records.get(artifactId);
+      if (current?.ownerId !== ownerId)
+        return [];
+      return (revisions.get(artifactId) ?? []).toSorted((left, right) => right.revision - left.revision).map(clone);
+    },
     save: async (record, expectedRevision) => {
       const current = records.get(record.id);
       if (!current || current.ownerId !== record.ownerId || current.revision !== expectedRevision) {
         return false;
       }
       records.set(record.id, clone(record));
+      revisions.set(record.id, [
+        ...revisions.get(record.id) ?? [],
+        clone(record)
+      ]);
       return true;
     }
   };
 };
 // src/tools.ts
-import { Type } from "@sinclair/typebox";
+import { Type as Type2 } from "@sinclair/typebox";
 var record = (input) => input && typeof input === "object" && !Array.isArray(input) ? input : {};
 var stringValue = (input, key) => typeof input[key] === "string" ? input[key] : undefined;
 var createArtifactTools = (options) => ({
@@ -214,10 +457,10 @@ var createArtifactTools = (options) => ({
       });
       return JSON.stringify(artifact);
     },
-    input: Type.Object({
-      content: Type.Unknown(),
-      kind: Type.String({ minLength: 1 }),
-      title: Type.String({ minLength: 1 })
+    input: Type2.Object({
+      content: Type2.Unknown(),
+      kind: Type2.String({ minLength: 1 }),
+      title: Type2.String({ minLength: 1 })
     })
   },
   artifact_get: {
@@ -229,7 +472,7 @@ var createArtifactTools = (options) => ({
         return "Provide artifactId.";
       return JSON.stringify(await options.service.get(options.ownerId, artifactId));
     },
-    input: Type.Object({ artifactId: Type.String({ minLength: 1 }) })
+    input: Type2.Object({ artifactId: Type2.String({ minLength: 1 }) })
   },
   artifact_list: {
     annotations: { readOnlyHint: true },
@@ -242,11 +485,22 @@ var createArtifactTools = (options) => ({
         status: ARTIFACT_STATUSES.find((candidate) => candidate === status)
       }));
     },
-    input: Type.Object({
-      kind: Type.Optional(Type.String()),
-      status: Type.Optional(Type.Union(ARTIFACT_STATUSES.map((status) => Type.Literal(status))))
+    input: Type2.Object({
+      kind: Type2.Optional(Type2.String()),
+      status: Type2.Optional(Type2.Union(ARTIFACT_STATUSES.map((status) => Type2.Literal(status))))
     })
   },
+  artifact_history: {
+    annotations: { readOnlyHint: true },
+    description: "List the immutable revisions of one owned artifact.",
+    handler: async (raw) => {
+      const artifactId = stringValue(record(raw), "artifactId");
+      if (!artifactId)
+        return "Provide artifactId.";
+      return JSON.stringify(await options.service.listRevisions(options.ownerId, artifactId));
+    },
+    input: Type2.Object({ artifactId: Type2.String({ minLength: 1 }) })
+  },
   artifact_publish: {
     description: "Publish or unpublish an artifact. Hosts should expose this tool only when the user explicitly controls public access.",
     handler: async (raw) => {
@@ -258,9 +512,25 @@ var createArtifactTools = (options) => ({
       const artifact = input.published ? await options.service.publish(options.ownerId, artifactId) : await options.service.unpublish(options.ownerId, artifactId);
       return JSON.stringify(artifact);
     },
-    input: Type.Object({
-      artifactId: Type.String({ minLength: 1 }),
-      published: Type.Boolean()
+    input: Type2.Object({
+      artifactId: Type2.String({ minLength: 1 }),
+      published: Type2.Boolean()
+    })
+  },
+  artifact_restore: {
+    description: "Restore an immutable artifact revision as a new private draft revision.",
+    handler: async (raw) => {
+      const input = record(raw);
+      const artifactId = stringValue(input, "artifactId");
+      if (!artifactId || typeof input.revision !== "number") {
+        return "Provide artifactId and revision.";
+      }
+      return JSON.stringify(await options.service.restore(options.ownerId, artifactId, input.revision, typeof input.expectedRevision === "number" ? input.expectedRevision : undefined));
+    },
+    input: Type2.Object({
+      artifactId: Type2.String({ minLength: 1 }),
+      expectedRevision: Type2.Optional(Type2.Integer({ minimum: 1 })),
+      revision: Type2.Integer({ minimum: 1 })
     })
   },
   artifact_update: {
@@ -277,20 +547,23 @@ var createArtifactTools = (options) => ({
       });
       return JSON.stringify(artifact);
     },
-    input: Type.Object({
-      artifactId: Type.String({ minLength: 1 }),
-      content: Type.Optional(Type.Unknown()),
-      expectedRevision: Type.Optional(Type.Integer({ minimum: 1 })),
-      title: Type.Optional(Type.String({ minLength: 1 }))
+    input: Type2.Object({
+      artifactId: Type2.String({ minLength: 1 }),
+      content: Type2.Optional(Type2.Unknown()),
+      expectedRevision: Type2.Optional(Type2.Integer({ minimum: 1 })),
+      title: Type2.Optional(Type2.String({ minLength: 1 }))
     })
   }
 });
 export {
+  standardArtifactDefinitions,
   defineArtifactRegistry,
   createMemoryArtifactStore,
+  createMemoryArtifactAssetStore,
   createArtifactTools,
   createArtifactService,
   createArtifactRendererRegistry,
+  STANDARD_ARTIFACT_KIND_NAMES,
   ArtifactError,
   ARTIFACT_STATUSES
 };

package/dist/manifest.js

@@ -5954,6 +5954,24 @@ var manifest = defineManifest()({
         kind: Type2.Optional(Type2.String({ minLength: 1 })),
         ownerId: Type2.String({ minLength: 1 })
       })
+    }),
+    artifact_history: tool.runtime({
+      annotations: { readOnlyHint: true },
+      description: "List immutable revisions of one artifact owned by a user.",
+      handler: async ({ artifactId, ownerId }, service) => JSON.stringify(await service.listRevisions(ownerId, artifactId)),
+      input: Type2.Object({
+        artifactId: Type2.String({ minLength: 1 }),
+        ownerId: Type2.String({ minLength: 1 })
+      })
+    }),
+    artifact_restore: tool.runtime({
+      description: "Restore an old artifact revision as a new private draft.",
+      handler: async ({ artifactId, ownerId, revision }, service) => JSON.stringify(await service.restore(ownerId, artifactId, revision)),
+      input: Type2.Object({
+        artifactId: Type2.String({ minLength: 1 }),
+        ownerId: Type2.String({ minLength: 1 }),
+        revision: Type2.Integer({ minimum: 1 })
+      })
     })
   },
   wiring: [

package/dist/manifest.json

@@ -95,6 +95,56 @@
 				}
 			},
 			"kind": "runtime"
+		},
+		"artifact_history": {
+			"annotations": {
+				"readOnlyHint": true
+			},
+			"description": "List immutable revisions of one artifact owned by a user.",
+			"input": {
+				"type": "object",
+				"required": [
+					"artifactId",
+					"ownerId"
+				],
+				"properties": {
+					"artifactId": {
+						"minLength": 1,
+						"type": "string"
+					},
+					"ownerId": {
+						"minLength": 1,
+						"type": "string"
+					}
+				}
+			},
+			"kind": "runtime"
+		},
+		"artifact_restore": {
+			"description": "Restore an old artifact revision as a new private draft.",
+			"input": {
+				"type": "object",
+				"required": [
+					"artifactId",
+					"ownerId",
+					"revision"
+				],
+				"properties": {
+					"artifactId": {
+						"minLength": 1,
+						"type": "string"
+					},
+					"ownerId": {
+						"minLength": 1,
+						"type": "string"
+					},
+					"revision": {
+						"minimum": 1,
+						"type": "integer"
+					}
+				}
+			},
+			"kind": "runtime"
 		}
 	}
 }

package/dist/rag.js

@@ -0,0 +1,44 @@
+// @bun
+// src/rag.ts
+import { Buffer } from "buffer";
+var artifactMetadata = (artifact) => ({
+  artifactId: artifact.id,
+  artifactKind: artifact.kind,
+  artifactRevision: artifact.revision,
+  artifactStatus: artifact.status,
+  ...artifact.metadata
+});
+var artifactToRAGUploads = async (artifact, reader, options = {}) => {
+  const metadata = artifactMetadata(artifact);
+  const uploads = await Promise.all(artifact.assets.map(async (asset) => ({
+    content: Buffer.from(await reader.read(asset, { artifact })).toString("base64"),
+    contentType: asset.mediaType,
+    encoding: "base64",
+    metadata: {
+      ...metadata,
+      artifactAssetId: asset.id,
+      artifactAssetRole: asset.role,
+      ...asset.metadata
+    },
+    name: asset.name,
+    source: `artifact:${artifact.id}:revision:${artifact.revision}:asset:${asset.id}`,
+    title: artifact.title
+  })));
+  if (options.includeStructuredContent === false)
+    return uploads;
+  return [
+    {
+      content: JSON.stringify(artifact.content),
+      contentType: "application/json",
+      encoding: "utf8",
+      metadata: { ...metadata, artifactStructuredContent: true },
+      name: `${artifact.kind}-${artifact.id}-r${artifact.revision}.json`,
+      source: `artifact:${artifact.id}:revision:${artifact.revision}:content`,
+      title: artifact.title
+    },
+    ...uploads
+  ];
+};
+export {
+  artifactToRAGUploads
+};

package/dist/src/index.d.ts

@@ -7,8 +7,9 @@
  * retains authorization, persistence, URLs, UI, and delivery policy.
  */
 export { defineArtifactRegistry, type ArtifactContent, type ArtifactKindDefinition, type ArtifactKindDefinitions, type ArtifactRegistry, } from "./registry";
+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, type ArtifactStore } from "./store";
+export { createMemoryArtifactStore, createMemoryArtifactAssetStore, type ArtifactAssetStore, type ArtifactStore, } from "./store";
 export { createArtifactTools, type ArtifactToolDefinition, type ArtifactToolMap, type ArtifactToolOptions, } from "./tools";
-export { ARTIFACT_STATUSES, ArtifactError, type ArtifactCapability, type ArtifactCreateInput, type ArtifactErrorCode, type ArtifactListQuery, type ArtifactProvenance, type ArtifactPublication, type ArtifactRecord, type ArtifactStatus, type ArtifactUpdateInput, } from "./types";
+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";

package/dist/src/manifest.d.ts

@@ -1,9 +1,18 @@
 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>;
     create: (ownerId: string, input: import("./types").ArtifactCreateInput) => 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>;
+    getRevision: (ownerId: string, artifactId: string, revision: number) => Promise<Readonly<import("./types").ArtifactRecord<unknown>>>;
     list: (ownerId: string, query?: import("./types").ArtifactListQuery) => Promise<import("./types").ArtifactRecord[]>;
+    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>;
+    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>;
     update: (ownerId: string, artifactId: string, input: import("./types").ArtifactUpdateInput) => Promise<import("./types").ArtifactRecord>;
 }>;

package/dist/src/rag.d.ts

@@ -0,0 +1,15 @@
+import type { RAGDocumentUploadInput } from "@absolutejs/rag";
+import type { ArtifactAssetReference, ArtifactRecord } from "./types";
+export type ArtifactRAGAssetReader = {
+    read(reference: ArtifactAssetReference, context: {
+        artifact: ArtifactRecord;
+    }): Promise<Uint8Array>;
+};
+export type ArtifactRAGUploadOptions = {
+    includeStructuredContent?: boolean;
+};
+/**
+ * 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[]>;

package/dist/src/registry.d.ts

@@ -1,6 +1,12 @@
 import type { Static, TSchema } from "@sinclair/typebox";
 import { type ArtifactCapability } from "./types";
+export type ArtifactAssetPolicy = {
+    /** Exact media types or wildcards such as image/* and application/*. */
+    acceptedMediaTypes?: string[];
+    maxCount?: number;
+};
 export type ArtifactKindDefinition<TContent extends TSchema = TSchema> = {
+    assets?: ArtifactAssetPolicy;
     capabilities?: ArtifactCapability[];
     content: TContent;
     description?: string;

package/dist/src/service.d.ts

@@ -1,6 +1,6 @@
 import type { ArtifactKindDefinitions, ArtifactRegistry } from "./registry";
-import type { ArtifactStore } from "./store";
-import { type ArtifactCreateInput, type ArtifactListQuery, type ArtifactRecord, type ArtifactUpdateInput } from "./types";
+import type { ArtifactAssetStore, ArtifactStore } from "./store";
+import { type ArtifactAssetReference, type ArtifactAssetWriteInput, type ArtifactCreateInput, type ArtifactListQuery, type ArtifactRecord, type ArtifactUpdateInput } from "./types";
 export type ArtifactPublisher = {
     publish(artifact: ArtifactRecord, options: {
         idempotencyKey: string;
@@ -13,6 +13,7 @@ export type ArtifactPublisher = {
     }): Promise<void>;
 };
 export type ArtifactServiceOptions<TDefinitions extends ArtifactKindDefinitions = ArtifactKindDefinitions> = {
+    assetStore?: ArtifactAssetStore;
     clock?: () => Date;
     idFactory?: () => string;
     publisher?: ArtifactPublisher;
@@ -22,10 +23,19 @@ export type ArtifactServiceOptions<TDefinitions extends ArtifactKindDefinitions
 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>;
     create: (ownerId: string, input: ArtifactCreateInput) => Promise<ArtifactRecord>;
+    detach: (ownerId: string, artifactId: string, assetId: string, expectedRevision?: number) => Promise<ArtifactRecord>;
     get: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
+    getRevision: (ownerId: string, artifactId: string, revision: number) => Promise<Readonly<ArtifactRecord<unknown>>>;
     list: (ownerId: string, query?: ArtifactListQuery) => Promise<ArtifactRecord[]>;
+    listRevisions: (ownerId: string, artifactId: string) => Promise<Readonly<ArtifactRecord<unknown>>[]>;
     publish: (ownerId: string, artifactId: string) => Promise<ArtifactRecord>;
     unpublish: (ownerId: string, artifactId: string) => 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>;
     update: (ownerId: string, artifactId: string, input: ArtifactUpdateInput) => Promise<ArtifactRecord>;
 };

package/dist/src/standardKinds.d.ts

@@ -0,0 +1,157 @@
+export declare const standardArtifactDefinitions: {
+    archive: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    audio: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    code: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    dataset: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    document: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    email: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    file: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    image: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    presentation: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    spreadsheet: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+    video: {
+        assets: {
+            acceptedMediaTypes: string[];
+            maxCount: number;
+        };
+        capabilities: ("attach" | "archive" | "edit" | "export" | "preview" | "refine")[];
+        content: import("@sinclair/typebox").TObject<{
+            description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            instructions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            summary: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>;
+        label: string;
+        schemaVersion: number;
+    };
+};
+export declare const STANDARD_ARTIFACT_KIND_NAMES: Array<keyof typeof standardArtifactDefinitions>;

package/dist/src/store.d.ts

@@ -1,8 +1,22 @@
-import type { ArtifactListQuery, ArtifactRecord } from "./types";
+import type { ArtifactAssetReference, ArtifactAssetWriteInput, ArtifactListQuery, ArtifactRecord, ArtifactRevision } from "./types";
+export type ArtifactAssetStore = {
+    read(reference: ArtifactAssetReference, context: {
+        artifact: ArtifactRecord;
+    }): Promise<Uint8Array>;
+    write(input: ArtifactAssetWriteInput, context: {
+        artifact: ArtifactRecord;
+        idempotencyKey: string;
+    }): Promise<ArtifactAssetReference>;
+};
 export type ArtifactStore = {
+    /** Persist the current record and its first immutable revision atomically. */
     create(record: ArtifactRecord): Promise<void>;
     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[]>;
+    /** Compare, replace current state, and append its revision atomically. */
     save(record: ArtifactRecord, expectedRevision: number): Promise<boolean>;
 };
+export declare const createMemoryArtifactAssetStore: () => ArtifactAssetStore;
 export declare const createMemoryArtifactStore: (initial?: ArtifactRecord[]) => ArtifactStore;

package/dist/src/types.d.ts

@@ -1,6 +1,6 @@
 export declare const ARTIFACT_STATUSES: readonly ["draft", "published", "archived"];
 export type ArtifactStatus = (typeof ARTIFACT_STATUSES)[number];
-export type ArtifactCapability = "archive" | "edit" | "export" | "preview" | "publish" | "refine";
+export type ArtifactCapability = "attach" | "archive" | "edit" | "export" | "preview" | "publish" | "refine";
 export type ArtifactProvenance = {
     model?: string;
     sourceIds?: string[];
@@ -12,7 +12,30 @@ export type ArtifactPublication = {
     publishedAt: string;
     url: string;
 };
+export type ArtifactAssetRole = "attachment" | "primary" | "preview" | "source";
+export type ArtifactAssetReference = {
+    checksum?: {
+        algorithm: "sha256";
+        value: string;
+    };
+    id: string;
+    mediaType: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    role: ArtifactAssetRole;
+    size: number;
+    /** Opaque host storage locator. It is not required to be publicly fetchable. */
+    uri: string;
+};
+export type ArtifactAssetWriteInput = {
+    data: Uint8Array;
+    mediaType: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    role?: ArtifactAssetRole;
+};
 export type ArtifactRecord<TContent = unknown> = {
+    assets: ArtifactAssetReference[];
     capabilities: ArtifactCapability[];
     content: TContent;
     createdAt: string;
@@ -29,12 +52,15 @@ export type ArtifactRecord<TContent = unknown> = {
     title: string;
     updatedAt: string;
 };
+/** An immutable point-in-time copy of an artifact record. */
+export type ArtifactRevision<TContent = unknown> = Readonly<ArtifactRecord<TContent>>;
 export type ArtifactListQuery = {
     kind?: string;
     limit?: number;
     status?: ArtifactStatus;
 };
 export type ArtifactCreateInput = {
+    assets?: ArtifactAssetReference[];
     content: unknown;
     createdBy: string;
     kind: string;
@@ -43,12 +69,13 @@ export type ArtifactCreateInput = {
     title: string;
 };
 export type ArtifactUpdateInput = {
+    assets?: ArtifactAssetReference[];
     content?: unknown;
     expectedRevision?: number;
     metadata?: Record<string, unknown>;
     title?: string;
 };
-export type ArtifactErrorCode = "conflict" | "invalid_content" | "not_found" | "publisher_unavailable" | "renderer_unavailable" | "unsupported_capability" | "unknown_kind";
+export type ArtifactErrorCode = "asset_store_unavailable" | "conflict" | "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.1",
+  "version": "0.0.2",
   "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",
@@ -14,14 +14,14 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/absolutejs/artifacts.git"
+    "url": "git+https://github.com/absolutejs/artifacts.git"
   },
   "homepage": "https://github.com/absolutejs/artifacts",
   "bugs": {
     "url": "https://github.com/absolutejs/artifacts/issues"
   },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --root ./src --target=bun --external @sinclair/typebox --external @sinclair/typebox/value && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
+    "build": "rm -rf dist && bun build src/index.ts src/manifest.ts src/rag.ts --outdir dist --root ./src --target=bun --external @absolutejs/rag --external @sinclair/typebox --external @sinclair/typebox/value && tsc --emitDeclarationOnly --project tsconfig.json && absolute-manifest emit",
     "format": "prettier --write \"./**/*.{ts,json,md}\"",
     "release": "bun run format && bun run test && bun run build && bun publish",
     "test": "bun test",
@@ -44,13 +44,27 @@
       "import": "./dist/manifest.js",
       "default": "./dist/manifest.js"
     },
-    "./manifest.json": "./dist/manifest.json"
+    "./manifest.json": "./dist/manifest.json",
+    "./rag": {
+      "types": "./dist/src/rag.d.ts",
+      "import": "./dist/rag.js",
+      "default": "./dist/rag.js"
+    }
   },
   "dependencies": {
     "@absolutejs/manifest": "^0.1.0",
     "@sinclair/typebox": "^0.34.0"
   },
+  "peerDependencies": {
+    "@absolutejs/rag": ">=0.0.29"
+  },
+  "peerDependenciesMeta": {
+    "@absolutejs/rag": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@absolutejs/rag": "0.0.29",
     "@types/bun": "latest",
     "prettier": "3.5.3",
     "typescript": "5.8.3"