@happyvertical/smrt-assets 0.30.0

package/dist/index.js

@@ -0,0 +1,2285 @@
+import { ObjectRegistry, foreignKey, smrt, SmrtPolymorphicAssociation, SmrtJunction, SmrtObject, crossPackageRef, SmrtCollection, SmrtHierarchical } from "@happyvertical/smrt-core";
+import { Tag } from "@happyvertical/smrt-tags";
+import { tenantId, TenantScoped, withSystemContext } from "@happyvertical/smrt-tenancy";
+import { getFilesystem, FileNotFoundError } from "@happyvertical/files";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$6 = Object.getOwnPropertyDescriptor;
+var __decorateClass$6 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$6(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$3(target, key, result);
+  return result;
+};
+let AssetAssociation = class extends SmrtPolymorphicAssociation {
+  tenantId = null;
+  assetId = "";
+  constructor(options = {}) {
+    super(options);
+    if (options.assetId) this.assetId = options.assetId;
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+  }
+};
+__decorateClass$6([
+  tenantId({ nullable: true })
+], AssetAssociation.prototype, "tenantId", 2);
+__decorateClass$6([
+  foreignKey("Asset", { required: true })
+], AssetAssociation.prototype, "assetId", 2);
+AssetAssociation = __decorateClass$6([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    conflictColumns: ["asset_id", "meta_type", "meta_id", "role"],
+    api: { include: ["list", "get", "create", "delete"] },
+    mcp: { include: ["list", "get", "create"] },
+    cli: true
+  })
+], AssetAssociation);
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$5 = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __decorateClass$5 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$5(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, key + "", value);
+let AssetAssociationCollection = class extends SmrtJunction {
+  // Composite left = (metaType, metaId); right = assetId.
+  // `leftField` placeholder satisfies the abstract base — the overrides below
+  // always handle the composite key explicitly.
+  leftField = "metaId";
+  rightField = "assetId";
+  /**
+   * List associations for a polymorphic owner.
+   *
+   * Composite left key — pass both halves.
+   */
+  // @ts-expect-error — diverges from SmrtJunction.byLeft(leftId) by arity; see class docstring.
+  async byLeft(metaType, metaId, opts = {}) {
+    return await this.list({
+      // Spread opts first so the fixed polymorphic owner keys always win.
+      where: { ...opts, metaType, metaId },
+      orderBy: "sort_order ASC"
+    });
+  }
+  /**
+   * Create an association. Composite left (metaType, metaId) precedes right (assetId).
+   */
+  // @ts-expect-error — diverges from SmrtJunction.attach(leftId, rightId) by arity.
+  async attach(metaType, metaId, assetId, opts = {}) {
+    return await this.create({
+      // Spread opts first so the fixed key fields always win.
+      ...opts,
+      assetId,
+      metaType,
+      metaId
+    });
+  }
+  /**
+   * Delete matching associations. Composite left (metaType, metaId) precedes right (assetId).
+   */
+  // @ts-expect-error — diverges from SmrtJunction.detach(leftId, rightId) by arity.
+  async detach(metaType, metaId, assetId, opts = {}) {
+    const links = await this.list({
+      where: { ...opts, metaType, metaId, assetId }
+    });
+    for (const link of links) {
+      await link.delete();
+    }
+  }
+  /**
+   * Replace all associations for a polymorphic owner with the given asset IDs.
+   * Not transactional — see `SmrtJunction.setLinks` for caveats.
+   */
+  // @ts-expect-error — diverges from SmrtJunction.setLinks(leftId, rightIds) by arity.
+  async setLinks(metaType, metaId, assetIds, opts = {}) {
+    const snapshotOpts = { ...opts };
+    delete snapshotOpts.assetId;
+    const existing = await this.list({
+      where: { ...snapshotOpts, metaType, metaId }
+    });
+    for (const link of existing) {
+      await link.delete();
+    }
+    const positionKey = this.positionField;
+    for (let i = 0; i < assetIds.length; i++) {
+      const rowOpts = { ...opts };
+      if (positionKey && rowOpts[positionKey] === void 0) {
+        rowOpts[positionKey] = i;
+      }
+      await this.attach(metaType, metaId, assetIds[i], rowOpts);
+    }
+  }
+};
+__publicField(AssetAssociationCollection, "_itemClass", AssetAssociation);
+AssetAssociationCollection = __decorateClass$5([
+  smrt()
+], AssetAssociationCollection);
+var __getOwnPropDesc$4 = Object.getOwnPropertyDescriptor;
+var __decorateClass$4 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$4(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+let AssetStatus = class extends SmrtObject {
+  // slug is inherited as an accessor from SmrtObject
+  name = "";
+  // Display name (e.g., 'Draft', 'Published')
+  description = "";
+  // Optional description
+  constructor(options = {}) {
+    super(options);
+    if (options.slug) this.slug = options.slug;
+    if (options.name) this.name = options.name;
+    if (options.description) this.description = options.description;
+  }
+  /**
+   * Get asset status by slug
+   *
+   * @param slug - The slug to search for
+   * @returns AssetStatus instance or null
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+AssetStatus = __decorateClass$4([
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create"] },
+    cli: true
+  })
+], AssetStatus);
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __decorateClass$3 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+let AssetType = class extends SmrtObject {
+  // slug is inherited as an accessor from SmrtObject
+  name = "";
+  // Display name (e.g., 'Image', 'Video')
+  description = "";
+  // Optional description
+  constructor(options = {}) {
+    super(options);
+    if (options.slug) this.slug = options.slug;
+    if (options.name) this.name = options.name;
+    if (options.description) this.description = options.description;
+  }
+  /**
+   * Get asset type by slug
+   *
+   * @param slug - The slug to search for
+   * @returns AssetType instance or null
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+AssetType = __decorateClass$3([
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create"] },
+    cli: true
+  })
+], AssetType);
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$1(target, key, result);
+  return result;
+};
+function parseAssetRecord(value) {
+  if (!value) return {};
+  if (typeof value !== "string") return value;
+  if (!value.trim()) return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function stringifyAssetRecord(value) {
+  if (!value || Object.keys(value).length === 0) return "";
+  return JSON.stringify(value);
+}
+let Asset = class extends SmrtObject {
+  tenantId = null;
+  // Core fields
+  name = "";
+  // User-friendly name
+  // slug is inherited as an accessor from SmrtObject
+  sourceUri = "";
+  // URI to the actual file (e.g., 's3://bucket/key', 'file:///path')
+  mimeType = "";
+  // MIME type (e.g., 'image/jpeg', 'video/mp4')
+  description = "";
+  // Optional description
+  metadata = "";
+  // JSON metadata owned by SMRT asset processors
+  version = 1;
+  primaryVersionId = null;
+  // Points to first version's ID
+  typeSlug = "";
+  // FK to AssetType.slug
+  statusSlug = "";
+  ownerProfileId = null;
+  sourceAssetId = null;
+  folderId = null;
+  // FK to Folder.id
+  // Provenance fields
+  sourceType = "";
+  // 'local', 'shutterstock', 'google-photos', 'upstream-smrt'
+  externalId = "";
+  // Original ID in upstream source
+  externalRefs = "";
+  // JSON map of provider references, keyed by provider slug
+  // Timestamps
+  createdAt = /* @__PURE__ */ new Date();
+  updatedAt = /* @__PURE__ */ new Date();
+  constructor(options = {}) {
+    super(options);
+    if (options.name) this.name = options.name;
+    if (options.slug) this.slug = options.slug;
+    if (options.sourceUri) this.sourceUri = options.sourceUri;
+    if (options.mimeType) this.mimeType = options.mimeType;
+    if (options.description) this.description = options.description;
+    if (options.metadata !== void 0)
+      this.metadata = typeof options.metadata === "string" ? options.metadata : stringifyAssetRecord(options.metadata);
+    if (options.version !== void 0) this.version = options.version;
+    if (options.primaryVersionId !== void 0)
+      this.primaryVersionId = options.primaryVersionId;
+    if (options.typeSlug) this.typeSlug = options.typeSlug;
+    if (options.statusSlug) this.statusSlug = options.statusSlug;
+    if (options.ownerProfileId !== void 0)
+      this.ownerProfileId = options.ownerProfileId;
+    if (options.sourceAssetId !== void 0)
+      this.sourceAssetId = options.sourceAssetId;
+    if (options.folderId !== void 0) this.folderId = options.folderId;
+    if (options.sourceType) this.sourceType = options.sourceType;
+    if (options.externalId) this.externalId = options.externalId;
+    if (options.externalRefs !== void 0)
+      this.externalRefs = typeof options.externalRefs === "string" ? options.externalRefs : stringifyAssetRecord(options.externalRefs);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.createdAt) this.createdAt = options.createdAt;
+    if (options.updatedAt) this.updatedAt = options.updatedAt;
+  }
+  getMetadata() {
+    return parseAssetRecord(this.metadata);
+  }
+  setMetadata(metadata) {
+    this.metadata = stringifyAssetRecord(metadata);
+  }
+  mergeMetadata(metadata) {
+    this.setMetadata({
+      ...this.getMetadata(),
+      ...metadata
+    });
+  }
+  getExternalRefs() {
+    const refs = parseAssetRecord(this.externalRefs);
+    const normalized = {};
+    for (const [provider, value] of Object.entries(refs)) {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        normalized[provider] = {
+          ...value,
+          provider
+        };
+      }
+    }
+    return normalized;
+  }
+  getExternalRef(provider) {
+    return this.getExternalRefs()[provider] ?? null;
+  }
+  setExternalRef(provider, reference) {
+    this.externalRefs = stringifyAssetRecord({
+      ...this.getExternalRefs(),
+      [provider]: {
+        ...this.getExternalRef(provider) ?? {},
+        ...reference,
+        provider: reference.provider ?? provider
+      }
+    });
+  }
+  /**
+   * Get all tags for this asset from @happyvertical/smrt-tags
+   *
+   * @returns Array of Tag instances from @happyvertical/smrt-tags package
+   */
+  async getTags() {
+    const db = this.db;
+    const rows = await db.list("asset_tags", {
+      where: { asset_id: this.id }
+    });
+    const tags = [];
+    for (const row of rows) {
+      const tag = await Tag.getBySlug(row.tag_slug);
+      if (tag) tags.push(tag);
+    }
+    return tags;
+  }
+  /**
+   * Check if this asset has a specific tag
+   *
+   * @param tagSlug - The slug of the tag to check
+   * @returns True if the asset has this tag
+   */
+  async hasTag(tagSlug) {
+    const db = this.db;
+    const rows = await db.list("asset_tags", {
+      where: { asset_id: this.id, tag_slug: tagSlug }
+    });
+    return rows.length > 0;
+  }
+  /**
+   * Resolve the AssetCollection lazily. Going through `ObjectRegistry`
+   * mirrors the pattern used by `SmrtHierarchical._hierarchyCollection`
+   * so source/derivative lookups inherit tenant scoping and ORM
+   * hydration without hard-coding an import of `./assets` (which would
+   * create a module-import cycle).
+   *
+   * The return type is `SmrtCollection<Asset>` (the framework base, type-
+   * only import from core) rather than the concrete `AssetCollection` —
+   * importing the concrete class is what would create the cycle, but the
+   * base-class shape gives callers full `.get()` / `.list()` type
+   * safety here.
+   *
+   * R5-canon: hardcode the base Asset's qualified key so a different
+   * package also registering a class called `Asset` can't be picked
+   * by `findClass`'s multi-strategy fallback. Crucially we DON'T
+   * resolve via `this.constructor._smrtQualifiedName` — for an STI
+   * subclass like `Image`, that would yield the Image collection
+   * (which auto-filters `_meta_type = '...:Image'` on `get`/`list`),
+   * and `getSource()` / `getDerivatives()` would miss cross-type
+   * derivation links (Image derived from a plain Asset, etc.).
+   * `sourceAssetId` is a base-table derivation link, so it always
+   * resolves through the base Asset collection.
+   */
+  async _assetCollection() {
+    return await ObjectRegistry.getCollection(
+      "@happyvertical/smrt-assets:Asset",
+      this.options
+    );
+  }
+  /**
+   * Get the source asset this one was derived from, if any.
+   *
+   * Renamed from `getParent` in R3-D. The relationship is "I was produced
+   * from that asset" (e.g. a thumbnail's source is its original image),
+   * not a structural-hierarchy parent.
+   *
+   * Goes through the AssetCollection so tenant interceptors and ORM
+   * hydration apply — important because a tenant-scoped consumer with
+   * cross-tenant derivative chains would otherwise return assets from
+   * tenants the caller cannot see, and a raw `db.get` returns
+   * snake_case rows that leave camelCase props (e.g. `sourceUri`) at
+   * their constructor defaults.
+   *
+   * @returns Source Asset instance, or null if this asset has no source
+   */
+  async getSource() {
+    if (!this.sourceAssetId) return null;
+    const collection = await this._assetCollection();
+    return await collection.get({ id: this.sourceAssetId });
+  }
+  /**
+   * Get all assets derived from this one (e.g. thumbnails, variants,
+   * transcodes, AI edits).
+   *
+   * Renamed from `getChildren` in R3-D to match the derivation
+   * semantics. Goes through the AssetCollection so tenant interceptors
+   * and ORM hydration apply (see `getSource` for why this matters —
+   * the pre-R3-D `getChildren` used raw `db.list`, which both bypassed
+   * tenant scoping and dropped camelCase property hydration; that
+   * latent breakage is fixed here).
+   *
+   * @returns Array of derivative Asset instances
+   */
+  async getDerivatives() {
+    if (!this.id) return [];
+    const collection = await this._assetCollection();
+    return await collection.list({
+      where: { sourceAssetId: this.id }
+    });
+  }
+  /**
+   * Get the type of this asset
+   *
+   * @returns AssetType instance or null
+   */
+  async getType() {
+    if (!this.typeSlug) return null;
+    return await AssetType.getBySlug(this.typeSlug);
+  }
+  /**
+   * Get the status of this asset
+   *
+   * @returns AssetStatus instance or null
+   */
+  async getStatus() {
+    if (!this.statusSlug) return null;
+    return await AssetStatus.getBySlug(this.statusSlug);
+  }
+  /**
+   * Get all associations for this asset
+   *
+   * @returns Array of AssetAssociation instances
+   */
+  async getAssociations() {
+    const associations = await AssetAssociationCollection.create({
+      db: this.db
+    });
+    return await associations.byRight(this.id);
+  }
+  /**
+   * Associate this asset with a target object
+   *
+   * @param metaType - Target class name or qualified name (e.g., 'Article' or '@pkg:Article')
+   * @param metaId - Target object ID
+   * @param role - Association role (default: 'default')
+   * @returns The created AssetAssociation
+   */
+  async associateWith(metaType, metaId, role = "default") {
+    const associations = await AssetAssociationCollection.create({
+      db: this.db
+    });
+    return await associations.attach(metaType, metaId, this.id, { role });
+  }
+  /**
+   * Get asset by slug
+   *
+   * @param slug - The slug to search for
+   * @returns Asset instance or null
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+__decorateClass$2([
+  tenantId({ nullable: true })
+], Asset.prototype, "tenantId", 2);
+__decorateClass$2([
+  foreignKey("Asset")
+], Asset.prototype, "primaryVersionId", 2);
+__decorateClass$2([
+  crossPackageRef("@happyvertical/smrt-profiles:Profile")
+], Asset.prototype, "ownerProfileId", 2);
+__decorateClass$2([
+  foreignKey("Asset")
+], Asset.prototype, "sourceAssetId", 2);
+__decorateClass$2([
+  foreignKey("Folder")
+], Asset.prototype, "folderId", 2);
+Asset = __decorateClass$2([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create", "update"] },
+    cli: true
+  })
+], Asset);
+class AssetCapabilityUnavailableError extends Error {
+  constructor(capability, message = `No asset capability provider is registered for ${capability}.`) {
+    super(message);
+    this.capability = capability;
+    this.name = "AssetCapabilityUnavailableError";
+  }
+  capability;
+}
+class AssetCapabilitySkippedError extends Error {
+  constructor(capability, message) {
+    super(message);
+    this.capability = capability;
+    this.name = "AssetCapabilitySkippedError";
+  }
+  capability;
+}
+const ASSET_ROLES = {
+  SOURCE_DOCUMENT: "source_document",
+  DOCUMENT_IMAGE: "document_image",
+  THUMBNAIL: "thumbnail",
+  ASSET_VARIANT: "asset_variant",
+  PROOF: "proof",
+  DERIVATION_SOURCE: "derivation_source",
+  ATTACHMENT: "attachment",
+  HERO: "hero"
+};
+const ASSET_METADATA_KEYS = {
+  EXTRACTION_STATUS: "extractionStatus",
+  EXTRACTION_ERROR: "extractionError",
+  EXTRACTED_AT: "extractedAt",
+  SOURCE_URL: "sourceUrl",
+  SOURCE_HASH: "sourceHash",
+  PAGE_NUMBER: "pageNumber"
+};
+const ASSET_EXTRACTION_STATUS = {
+  PENDING: "pending",
+  RUNNING: "running",
+  SUCCEEDED: "succeeded",
+  FAILED: "failed"
+};
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+let AssetMetafield = class extends SmrtObject {
+  // slug is inherited as an accessor from SmrtObject
+  name = "";
+  // Display name (e.g., 'Width', 'Height')
+  validation = "";
+  // JSON validation rules stored as text
+  constructor(options = {}) {
+    super(options);
+    if (options.slug) this.slug = options.slug;
+    if (options.name) this.name = options.name;
+    if (options.validation) this.validation = options.validation;
+  }
+  /**
+   * Get validation rules as parsed object
+   *
+   * @returns Parsed validation object or empty object if no validation
+   */
+  getValidation() {
+    if (!this.validation) return {};
+    try {
+      return JSON.parse(this.validation);
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Set validation rules from object
+   *
+   * @param rules - Validation rules object
+   */
+  setValidation(rules) {
+    this.validation = JSON.stringify(rules);
+  }
+  /**
+   * Get asset metafield by slug
+   *
+   * @param slug - The slug to search for
+   * @returns AssetMetafield instance or null
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+AssetMetafield = __decorateClass$1([
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create"] },
+    cli: true
+  })
+], AssetMetafield);
+class AssetMetafieldCollection extends SmrtCollection {
+  static _itemClass = AssetMetafield;
+  /**
+   * Get or create an asset metafield by slug
+   *
+   * @param slug - The metafield slug
+   * @param name - The display name (defaults to slug)
+   * @param validation - Optional validation rules (JSON string or object)
+   * @returns The existing or newly created AssetMetafield
+   */
+  async getOrCreate(slug, name, validation) {
+    const existing = await this.list({ where: { slug }, limit: 1 });
+    if (existing.length > 0) {
+      return existing[0];
+    }
+    const validationString = typeof validation === "string" ? validation : validation ? JSON.stringify(validation) : "";
+    return await this.create({
+      slug,
+      name: name || slug,
+      validation: validationString
+    });
+  }
+  /**
+   * Initialize common asset metafields
+   *
+   * Creates standard metafields with validation rules:
+   * - width (integer, min: 0)
+   * - height (integer, min: 0)
+   * - duration (number, min: 0)
+   * - size (integer, min: 0)
+   * - author (string)
+   * - copyright (string)
+   */
+  async initializeCommonMetafields() {
+    await this.getOrCreate("width", "Width", {
+      type: "integer",
+      min: 0,
+      description: "Width in pixels"
+    });
+    await this.getOrCreate("height", "Height", {
+      type: "integer",
+      min: 0,
+      description: "Height in pixels"
+    });
+    await this.getOrCreate("duration", "Duration", {
+      type: "number",
+      min: 0,
+      description: "Duration in seconds"
+    });
+    await this.getOrCreate("size", "File Size", {
+      type: "integer",
+      min: 0,
+      description: "File size in bytes"
+    });
+    await this.getOrCreate("author", "Author", {
+      type: "string",
+      description: "Content creator"
+    });
+    await this.getOrCreate("copyright", "Copyright", {
+      type: "string",
+      description: "Copyright notice"
+    });
+  }
+}
+const MIME_TO_EXT = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/svg+xml": "svg",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "audio/wav": "wav",
+  "audio/mpeg": "mp3",
+  "audio/ogg": "ogg",
+  "audio/flac": "flac",
+  "application/pdf": "pdf",
+  "application/json": "json",
+  "text/plain": "txt"
+};
+function serializeStoreMetadata(metadata) {
+  if (metadata === void 0) return void 0;
+  if (metadata === null) return "";
+  if (typeof metadata === "string") return metadata;
+  return JSON.stringify(metadata);
+}
+function normalizeProviderOptions(providerOrBasePath) {
+  if (typeof providerOrBasePath === "string") {
+    return { type: "local", basePath: providerOrBasePath };
+  }
+  return providerOrBasePath;
+}
+class AssetStore {
+  constructor(providerOrBasePath, collection, options = {}) {
+    this.collection = collection;
+    this.fsOptions = normalizeProviderOptions(providerOrBasePath);
+    this.resolver = options.resolver;
+  }
+  collection;
+  fs = null;
+  fsOptions;
+  fsCache = /* @__PURE__ */ new Map();
+  resolver;
+  /** The base path for local storage, or empty string for non-local providers */
+  get basePath() {
+    return this.fsOptions.basePath ?? "";
+  }
+  /**
+   * Initialize the filesystem adapter.
+   * Must be called before any file operations.
+   */
+  async initialize() {
+    this.fs = await getFilesystem(this.fsOptions);
+    this.fsCache.set(this.providerCacheKey(this.fsOptions), this.fs);
+    return this;
+  }
+  /**
+   * Get the initialized filesystem (throws if not initialized)
+   */
+  getFs() {
+    if (!this.fs) {
+      throw new Error("AssetStore not initialized. Call initialize() first.");
+    }
+    return this.fs;
+  }
+  providerCacheKey(providerOptions) {
+    return JSON.stringify(providerOptions);
+  }
+  async getFilesystemForOptions(providerOptions) {
+    const key = this.providerCacheKey(providerOptions);
+    const cached = this.fsCache.get(key);
+    if (cached) return cached;
+    const filesystem = await getFilesystem(providerOptions);
+    this.fsCache.set(key, filesystem);
+    return filesystem;
+  }
+  /**
+   * Build a sourceUri for the given file path based on the provider type.
+   */
+  buildSourceUri(filePath) {
+    return AssetStore.buildSourceUriForProvider(filePath, this.fsOptions);
+  }
+  static buildSourceUriForProvider(filePath, providerOptions) {
+    const type = providerOptions.type;
+    if (type === "s3") {
+      const bucket = providerOptions.bucket ?? "";
+      return `s3://${bucket}/${filePath}`;
+    }
+    const base = providerOptions.basePath ?? "";
+    return base ? `file://${base}/${filePath}` : `file://${filePath}`;
+  }
+  static providerRelativePath(filePath, providerOptions) {
+    const base = providerOptions.basePath ?? "";
+    return base && filePath.startsWith(base) ? filePath.slice(base.length + 1) : filePath;
+  }
+  static requireAssetId(asset) {
+    if (!asset.id) {
+      throw new Error("Asset must be saved before storing file data.");
+    }
+    return asset.id;
+  }
+  async resolveStorage(request) {
+    const defaultFilesystem = this.getFs();
+    const resolution = this.resolver ? await this.resolver({
+      ...request,
+      defaultProviderOptions: this.fsOptions,
+      defaultFilesystem
+    }) : void 0;
+    if (request.operation === "write" && resolution?.filesystem && !resolution.providerOptions && !resolution.sourceUri) {
+      throw new Error(
+        "Asset storage resolver must return providerOptions or sourceUri when overriding filesystem for write operations."
+      );
+    }
+    const providerOptions = resolution?.providerOptions ? normalizeProviderOptions(resolution.providerOptions) : this.fsOptions;
+    const path = AssetStore.providerRelativePath(
+      resolution?.path ?? request.path,
+      providerOptions
+    );
+    const sourceUri = resolution?.sourceUri ?? (resolution?.path || resolution?.providerOptions ? AssetStore.buildSourceUriForProvider(path, providerOptions) : request.sourceUri);
+    const filesystem = resolution?.filesystem ?? (providerOptions === this.fsOptions ? defaultFilesystem : await this.getFilesystemForOptions(providerOptions));
+    return {
+      filesystem,
+      providerOptions,
+      path,
+      sourceUri
+    };
+  }
+  async writeAssetData(asset, data, opts) {
+    const ext = MIME_TO_EXT[opts.mimeType] ?? "bin";
+    const typeSlug = opts.typeSlug ?? "file";
+    const assetId = AssetStore.requireAssetId(asset);
+    const filePath = `${typeSlug}/${assetId}.${ext}`;
+    const sourceUri = this.buildSourceUri(filePath);
+    const target = await this.resolveStorage({
+      operation: "write",
+      asset,
+      path: filePath,
+      sourceUri,
+      mimeType: opts.mimeType,
+      typeSlug
+    });
+    await target.filesystem.write(target.path, data, { createParents: true });
+    return target.sourceUri;
+  }
+  /**
+   * Write file data for an existing Asset record (no DB record created).
+   *
+   * Use this when you've already created the record (e.g., via a
+   * collection.create()) and only need to persist the file data.
+   *
+   * @param asset - The existing asset to write data for
+   * @param data - File data as a Buffer
+   * @param opts - Storage options (mimeType required)
+   * @returns The sourceUri for the written file
+   */
+  async storeFile(asset, data, opts) {
+    return this.writeAssetData(asset, data, opts);
+  }
+  /**
+   * Write buffer to disk and create an Asset record.
+   *
+   * @param name - Human-readable name for the asset
+   * @param data - File data as a Buffer
+   * @param opts - Storage options (mimeType required)
+   * @returns Created Asset instance
+   */
+  async store(name, data, opts) {
+    const typeSlug = opts.typeSlug ?? "file";
+    const asset = await this.collection.create({
+      name,
+      mimeType: opts.mimeType,
+      typeSlug,
+      statusSlug: opts.statusSlug ?? "active",
+      sourceAssetId: opts.sourceAssetId ?? null,
+      description: opts.description ?? "",
+      sourceType: opts.sourceType ?? "",
+      externalId: opts.externalId ?? "",
+      metadata: serializeStoreMetadata(opts.metadata) ?? "",
+      sourceUri: ""
+      // Will be updated after file write
+    });
+    try {
+      asset.sourceUri = await this.writeAssetData(asset, data, {
+        mimeType: opts.mimeType,
+        typeSlug
+      });
+    } catch (err) {
+      await asset.delete();
+      throw err;
+    }
+    await asset.save();
+    return asset;
+  }
+  /**
+   * Store a new version of an existing asset.
+   *
+   * @param asset - The existing asset to version
+   * @param data - File data for the new version
+   * @param opts - Optional overrides for store options
+   * @returns The newly created version Asset
+   */
+  async storeVersion(asset, data, opts = {}) {
+    const primaryVersionId = asset.primaryVersionId ?? AssetStore.requireAssetId(asset);
+    const { metadata, ...versionOptions } = opts;
+    const versionUpdates = { ...versionOptions };
+    const serializedMetadata = serializeStoreMetadata(metadata);
+    if (serializedMetadata !== void 0) {
+      versionUpdates.metadata = serializedMetadata;
+    } else {
+      delete versionUpdates.metadata;
+    }
+    const newVersion = await this.collection.createNewVersion(
+      primaryVersionId,
+      "",
+      // sourceUri will be set by store
+      versionUpdates
+    );
+    const mimeType = opts.mimeType ?? asset.mimeType;
+    const typeSlug = opts.typeSlug ?? asset.typeSlug ?? "file";
+    try {
+      newVersion.sourceUri = await this.writeAssetData(newVersion, data, {
+        mimeType,
+        typeSlug
+      });
+    } catch (err) {
+      await newVersion.delete();
+      throw err;
+    }
+    if (opts.mimeType) newVersion.mimeType = opts.mimeType;
+    await newVersion.save();
+    return newVersion;
+  }
+  /**
+   * Read file data for a specific version of an asset.
+   *
+   * @param asset - The asset (any version in the chain)
+   * @param version - The version number to read
+   * @returns File data as a Buffer
+   */
+  async readVersion(asset, version) {
+    const primaryVersionId = asset.primaryVersionId ?? AssetStore.requireAssetId(asset);
+    const versions = await this.collection.listVersions(primaryVersionId);
+    const targetVersion = versions.find((v) => v.version === version);
+    if (!targetVersion) {
+      throw new Error(
+        `Version ${version} not found for asset ${primaryVersionId}`
+      );
+    }
+    return this.read(targetVersion);
+  }
+  /**
+   * Read file data from an Asset's sourceUri.
+   *
+   * @param asset - Asset to read data for
+   * @returns File data as a Buffer
+   */
+  async read(asset) {
+    const filePath = AssetStore.pathFromUri(asset.sourceUri);
+    const target = await this.resolveStorage({
+      operation: "read",
+      asset,
+      path: AssetStore.providerRelativePath(filePath, this.fsOptions),
+      sourceUri: asset.sourceUri
+    });
+    return await target.filesystem.read(target.path, { raw: true });
+  }
+  /**
+   * Read file by asset ID.
+   *
+   * @param id - Asset ID to look up
+   * @returns Object with data Buffer and Asset, or null if not found
+   */
+  async readById(id) {
+    const asset = await this.collection.get({ id });
+    if (!asset) return null;
+    try {
+      const data = await this.read(asset);
+      return { data, asset };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Delete file from disk and remove the Asset record.
+   *
+   * @param asset - Asset to remove
+   */
+  async remove(asset) {
+    if (asset.sourceUri) {
+      const filePath = AssetStore.pathFromUri(asset.sourceUri);
+      const target = await this.resolveStorage({
+        operation: "delete",
+        asset,
+        path: AssetStore.providerRelativePath(filePath, this.fsOptions),
+        sourceUri: asset.sourceUri
+      });
+      try {
+        await target.filesystem.delete(target.path);
+      } catch (err) {
+        if (!(err instanceof FileNotFoundError)) {
+          throw err;
+        }
+      }
+    }
+    await asset.delete();
+  }
+  /**
+   * Extract filesystem path from a sourceUri.
+   * Handles file://, s3://, and plain paths.
+   *
+   * @param sourceUri - Asset sourceUri (e.g., 'file:///path/to/file.mp4', 's3://bucket/key')
+   * @returns Filesystem path
+   */
+  static pathFromUri(sourceUri) {
+    if (sourceUri.startsWith("file://")) {
+      return sourceUri.slice(7);
+    }
+    if (sourceUri.startsWith("s3://")) {
+      const withoutScheme = sourceUri.slice(5);
+      const slashIdx = withoutScheme.indexOf("/");
+      return slashIdx >= 0 ? withoutScheme.slice(slashIdx + 1) : withoutScheme;
+    }
+    return sourceUri;
+  }
+}
+class AssetCollection extends SmrtCollection {
+  static _itemClass = Asset;
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tenant-Aware Query Methods
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Find all assets belonging to a specific tenant
+   *
+   * @param tenantId - The tenant ID to filter by
+   * @returns Array of assets belonging to this tenant
+   */
+  async findByTenant(tenantId2) {
+    return await this.list({ where: { tenantId: tenantId2 } });
+  }
+  /**
+   * Find all global assets (assets without a tenant)
+   *
+   * @returns Array of global assets
+   */
+  async findGlobal() {
+    return await this.list({ where: { tenantId: null } });
+  }
+  /**
+   * Find assets belonging to a tenant plus all global assets
+   *
+   * @param tenantId - The tenant ID to include
+   * @returns Array of tenant-specific and global assets
+   */
+  async findWithGlobals(tenantId2) {
+    return await this.query(
+      `SELECT * FROM ${this.tableName} WHERE tenant_id = ? OR tenant_id IS NULL`,
+      [tenantId2]
+    );
+  }
+  /**
+   * Add a tag to an asset (uses @smrt/tags)
+   *
+   * @param assetId - The asset ID to tag
+   * @param tagSlug - The tag slug from @smrt/tags
+   */
+  async addTag(assetId, tagSlug) {
+    const db = this.db;
+    await db.upsert("asset_tags", ["asset_id", "tag_slug"], {
+      asset_id: assetId,
+      tag_slug: tagSlug,
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /**
+   * Remove a tag from an asset
+   *
+   * @param assetId - The asset ID
+   * @param tagSlug - The tag slug to remove
+   */
+  async removeTag(assetId, tagSlug) {
+    const db = this.db;
+    await db.delete("asset_tags", {
+      asset_id: assetId,
+      tag_slug: tagSlug
+    });
+  }
+  /**
+   * Get all assets with a specific tag
+   *
+   * @param tagSlug - The tag slug to filter by
+   * @returns Array of assets with this tag
+   */
+  async getByTag(tagSlug) {
+    const db = this.db;
+    const rows = await db.list("asset_tags", { tag_slug: tagSlug });
+    const assets = [];
+    for (const row of rows) {
+      const asset = await this.get({ id: row.asset_id });
+      if (asset) assets.push(asset);
+    }
+    return assets;
+  }
+  /**
+   * Get assets by type
+   *
+   * @param typeSlug - The asset type slug (e.g., 'image', 'video')
+   * @returns Array of assets matching the type
+   */
+  async getByType(typeSlug) {
+    return await this.list({ where: { typeSlug } });
+  }
+  /**
+   * Get assets by status
+   *
+   * @param statusSlug - The asset status slug (e.g., 'published', 'draft')
+   * @returns Array of assets matching the status
+   */
+  async getByStatus(statusSlug) {
+    return await this.list({ where: { statusSlug } });
+  }
+  /**
+   * Get assets by owner
+   *
+   * @param ownerProfileId - The profile ID of the owner
+   * @returns Array of assets owned by this profile
+   */
+  async getByOwner(ownerProfileId) {
+    return await this.list({ where: { ownerProfileId } });
+  }
+  /**
+   * Create a new version of an existing asset
+   *
+   * @param primaryVersionId - The primary version ID (first version's ID)
+   * @param newSourceUri - The new source URI for this version
+   * @param updates - Optional additional updates
+   * @returns The newly created asset version
+   */
+  async createNewVersion(primaryVersionId, newSourceUri, updates = {}) {
+    const versions = await this.listVersions(primaryVersionId);
+    if (versions.length === 0) {
+      throw new Error(
+        `No asset found with primary version ID: ${primaryVersionId}`
+      );
+    }
+    versions.sort((a, b) => b.version - a.version);
+    const latestVersion = versions[0];
+    const newVersionNumber = latestVersion.version + 1;
+    const primary = versions.find((v) => v.id === primaryVersionId) ?? versions[versions.length - 1];
+    const baseSlug = String(primary?.slug ?? "") || "asset";
+    const takenInChain = new Set(
+      versions.map((v) => v.slug).filter(Boolean)
+    );
+    let candidate = `${baseSlug}-v${newVersionNumber}`;
+    for (let attempt = 1; ; attempt += 1) {
+      const collides = takenInChain.has(candidate) || await this.get({ slug: candidate }) !== null;
+      if (!collides) break;
+      candidate = `${baseSlug}-v${newVersionNumber}-${attempt}`;
+    }
+    return await this.create({
+      ...latestVersion,
+      id: void 0,
+      // Generate new ID
+      slug: candidate,
+      sourceUri: newSourceUri,
+      version: newVersionNumber,
+      primaryVersionId,
+      createdAt: /* @__PURE__ */ new Date(),
+      updatedAt: /* @__PURE__ */ new Date(),
+      ...updates
+    });
+  }
+  /**
+   * Get the latest version of an asset
+   *
+   * @param primaryVersionId - The primary version ID
+   * @returns The latest version or null
+   */
+  async getLatestVersion(primaryVersionId) {
+    const versions = await this.listVersions(primaryVersionId);
+    if (versions.length === 0) return null;
+    versions.sort((a, b) => b.version - a.version);
+    return versions[0];
+  }
+  /**
+   * List all versions of an asset
+   *
+   * @param primaryVersionId - The primary version ID
+   * @returns Array of all asset versions, ordered by version number
+   */
+  async listVersions(primaryVersionId) {
+    const [chained, primary] = await Promise.all([
+      this.list({ where: { primaryVersionId } }),
+      this.get({ id: primaryVersionId })
+    ]);
+    const byId = /* @__PURE__ */ new Map();
+    for (const asset of [...primary ? [primary] : [], ...chained]) {
+      if (asset?.id) byId.set(asset.id, asset);
+    }
+    const assets = Array.from(byId.values());
+    assets.sort((a, b) => a.version - b.version);
+    return assets;
+  }
+  /**
+   * Get derivative assets of a source asset.
+   *
+   * Renamed from `getChildren(parentId)` in R3-D to match the rename of
+   * the underlying column (`parent_id` → `source_asset_id`) and method
+   * (`Asset.getChildren` → `Asset.getDerivatives`).
+   *
+   * @param sourceAssetId - The source asset ID
+   * @returns Array of derivative assets
+   */
+  async getDerivatives(sourceAssetId) {
+    return await this.list({ where: { sourceAssetId } });
+  }
+  /**
+   * Get assets by MIME type pattern
+   *
+   * @param mimePattern - MIME type pattern (e.g., 'image/*', 'video/mp4')
+   * @returns Array of matching assets
+   */
+  async getByMimeType(mimePattern) {
+    const pattern = mimePattern.replace("*", "%");
+    return await this.list({
+      where: { "mimeType like": pattern }
+    });
+  }
+  /**
+   * Rollback to a previous version by creating a new version with the target's content.
+   * Does NOT delete intermediate versions (safe rollback).
+   *
+   * @param primaryVersionId - The primary version ID of the version chain
+   * @param targetVersion - The version number to rollback to
+   * @returns The newly created asset version with content copied from target
+   */
+  async rollbackToVersion(primaryVersionId, targetVersion) {
+    const versions = await this.listVersions(primaryVersionId);
+    const target = versions.find((v) => v.version === targetVersion);
+    if (!target) {
+      throw new Error(
+        `Version ${targetVersion} not found for asset ${primaryVersionId}`
+      );
+    }
+    return await this.createNewVersion(primaryVersionId, target.sourceUri, {
+      description: `Rollback to version ${targetVersion}`
+    });
+  }
+  /**
+   * Get assets in a specific folder
+   *
+   * @param folderId - The folder ID to list contents for
+   * @returns Array of assets in this folder
+   */
+  async getByFolder(folderId) {
+    return await this.list({ where: { folderId } });
+  }
+}
+class AssetRuntime {
+  constructor(collection, associations, store, capabilityProviders = []) {
+    this.collection = collection;
+    this.associations = associations;
+    this.store = store;
+    this.capabilityProviders = [...capabilityProviders];
+  }
+  collection;
+  associations;
+  store;
+  capabilityProviders;
+  registerCapabilityProvider(provider) {
+    this.capabilityProviders.push(provider);
+    return this;
+  }
+  providersFor(capability) {
+    const providers = this.capabilityProviders.filter(
+      (candidate) => typeof candidate[capability] === "function"
+    );
+    if (providers.length === 0) {
+      throw new AssetCapabilityUnavailableError(capability);
+    }
+    return providers;
+  }
+  async processAsset(asset, input = {}) {
+    let skipped = null;
+    for (const provider of this.providersFor("processAsset")) {
+      const processAsset = provider.processAsset;
+      if (!processAsset) continue;
+      try {
+        return await processAsset({
+          runtime: this,
+          asset,
+          ...input
+        });
+      } catch (cause) {
+        if (cause instanceof AssetCapabilitySkippedError) {
+          skipped = cause;
+          continue;
+        }
+        throw cause;
+      }
+    }
+    throw new AssetCapabilityUnavailableError("processAsset", skipped?.message);
+  }
+  async ensureVariant(asset, request) {
+    let skipped = null;
+    for (const provider of this.providersFor("ensureVariant")) {
+      const ensureVariant = provider.ensureVariant;
+      if (!ensureVariant) continue;
+      try {
+        return await ensureVariant({
+          runtime: this,
+          asset,
+          request
+        });
+      } catch (cause) {
+        if (cause instanceof AssetCapabilitySkippedError) {
+          skipped = cause;
+          continue;
+        }
+        throw cause;
+      }
+    }
+    throw new AssetCapabilityUnavailableError(
+      "ensureVariant",
+      skipped?.message
+    );
+  }
+  async searchNearbyAssets(input) {
+    let skipped = null;
+    for (const provider of this.providersFor("searchNearbyAssets")) {
+      const searchNearbyAssets = provider.searchNearbyAssets;
+      if (!searchNearbyAssets) continue;
+      try {
+        return await searchNearbyAssets({
+          runtime: this,
+          ...input
+        });
+      } catch (cause) {
+        if (cause instanceof AssetCapabilitySkippedError) {
+          skipped = cause;
+          continue;
+        }
+        throw cause;
+      }
+    }
+    throw new AssetCapabilityUnavailableError(
+      "searchNearbyAssets",
+      skipped?.message
+    );
+  }
+  async syncExternalAsset(asset, input = {}) {
+    let skipped = null;
+    for (const provider of this.providersFor("syncExternalAsset")) {
+      const syncExternalAsset = provider.syncExternalAsset;
+      if (!syncExternalAsset) continue;
+      try {
+        return await syncExternalAsset({
+          runtime: this,
+          asset,
+          ...input
+        });
+      } catch (cause) {
+        if (cause instanceof AssetCapabilitySkippedError) {
+          skipped = cause;
+          continue;
+        }
+        throw cause;
+      }
+    }
+    throw new AssetCapabilityUnavailableError(
+      "syncExternalAsset",
+      skipped?.message
+    );
+  }
+  async submitAssetWorkflow(asset, input) {
+    let skipped = null;
+    for (const provider of this.providersFor("submitAssetWorkflow")) {
+      const submitAssetWorkflow = provider.submitAssetWorkflow;
+      if (!submitAssetWorkflow) continue;
+      try {
+        return await submitAssetWorkflow({
+          runtime: this,
+          asset,
+          ...input
+        });
+      } catch (cause) {
+        if (cause instanceof AssetCapabilitySkippedError) {
+          skipped = cause;
+          continue;
+        }
+        throw cause;
+      }
+    }
+    throw new AssetCapabilityUnavailableError(
+      "submitAssetWorkflow",
+      skipped?.message
+    );
+  }
+  /**
+   * Create a new source asset with both a record and bytes on disk.
+   *
+   * This is the same as `AssetStore.store()`, but exposed on the runtime
+   * so callers only need one handle.
+   */
+  storeSourceAsset(name, data, opts) {
+    return this.store.store(name, data, opts);
+  }
+  /**
+   * Create a derivative of `source`, persist its bytes, and optionally
+   * record a provenance association.
+   *
+   * The new asset's `sourceAssetId` always points at `source.id`. When
+   * `linkAssociation` is true (the default), the runtime also writes
+   * an `AssetAssociation` so queries by role (e.g. "all `document_image`
+   * derivatives for this `source_document`") work without scanning
+   * `source_asset_id` chains.
+   */
+  async storeDerivedAsset(source, name, data, opts) {
+    if (!source.id) {
+      throw new Error(
+        "storeDerivedAsset: source asset must be persisted (missing id)"
+      );
+    }
+    const {
+      role: rawRole,
+      linkAssociation = true,
+      derivativeMetaType = "Asset",
+      ...storeOpts
+    } = opts;
+    const role = rawRole ?? ASSET_ROLES.DERIVATION_SOURCE;
+    const derived = await this.store.store(name, data, {
+      ...storeOpts,
+      sourceAssetId: source.id
+    });
+    if (linkAssociation && derived.id) {
+      await this.associations.attach(
+        derivativeMetaType,
+        derived.id,
+        source.id,
+        { role }
+      );
+    }
+    return derived;
+  }
+  /**
+   * Record a provenance association between an existing source asset
+   * and an existing derivative asset without touching bytes.
+   */
+  async linkDerivation(source, derivative, opts = {}) {
+    if (!source.id || !derivative.id) {
+      throw new Error(
+        "linkDerivation: both source and derivative must be persisted (missing id)"
+      );
+    }
+    const role = opts.role ?? ASSET_ROLES.DERIVATION_SOURCE;
+    const derivativeMetaType = opts.derivativeMetaType ?? "Asset";
+    return this.associations.attach(
+      derivativeMetaType,
+      derivative.id,
+      source.id,
+      { role }
+    );
+  }
+  /**
+   * Update the standard extraction-status metadata on an asset's
+   * `description` JSON sidecar. This is a thin convenience over the
+   * convention in `asset-conventions.ts` — callers that store
+   * metadata elsewhere can ignore it.
+   *
+   * **How existing descriptions are handled**:
+   * - Empty / unset → fresh JSON object.
+   * - Valid JSON object → merged into; existing keys preserved.
+   * - Free-form prose or non-object JSON → preserved under the
+   *   reserved `text` key of the resulting object (e.g.
+   *   `{ text: "original prose", extractionStatus: "..." }`). No prose
+   *   is discarded.
+   *
+   * Callers that already use `text` for something else, or that need
+   * an entirely separate metadata surface, should either round-trip
+   * the JSON themselves or skip this helper — its only job is the
+   * `extractionStatus` / `extractionError` / `extractedAt` triple.
+   *
+   * Error handling: when `status` transitions away from `failed`
+   * without a new `extra.error`, the stale `extractionError` is
+   * cleared so downstream consumers don't misread the current state.
+   * When `status === 'succeeded'`, `extractedAt` is stamped to now
+   * unless the caller provides one.
+   */
+  async setExtractionStatus(asset, status, extra = {}) {
+    const existing = parseDescriptionSidecar(asset.description);
+    const next = {
+      ...existing,
+      extractionStatus: status
+    };
+    if (extra.error !== void 0) {
+      next.extractionError = extra.error;
+    } else if (status !== "failed") {
+      delete next.extractionError;
+    }
+    if (status === "succeeded") {
+      next.extractedAt = (extra.extractedAt ?? /* @__PURE__ */ new Date()).toISOString();
+    }
+    asset.description = JSON.stringify(next);
+    await asset.save();
+  }
+}
+async function createAssetRuntime(options) {
+  const collection = options.collection ?? await AssetCollection.create({ db: options.db });
+  const associations = options.associations ?? await AssetAssociationCollection.create({ db: options.db });
+  const store = await new AssetStore(
+    options.storage,
+    collection,
+    options.storeOptions
+  ).initialize();
+  return new AssetRuntime(
+    collection,
+    associations,
+    store,
+    options.capabilityProviders
+  );
+}
+function parseDescriptionSidecar(description) {
+  if (!description) return {};
+  try {
+    const parsed = JSON.parse(description);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    return { text: description };
+  } catch {
+    return { text: description };
+  }
+}
+const DEFAULT_REMOTE_MAX_BYTES = 50 * 1024 * 1024;
+const DEFAULT_REMOTE_TIMEOUT_MS = 1e4;
+const MAX_REMOTE_REDIRECTS = 5;
+const INLINE_SAFE_MIME_TYPES = /* @__PURE__ */ new Set([
+  "application/json",
+  "application/pdf",
+  "audio/aac",
+  "audio/mpeg",
+  "audio/ogg",
+  "audio/wav",
+  "audio/webm",
+  "image/avif",
+  "image/gif",
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "text/csv",
+  "text/plain",
+  "video/mp4",
+  "video/ogg",
+  "video/webm"
+]);
+function normalizeMimeType(raw) {
+  return (raw.split(";")[0] ?? "").trim().toLowerCase();
+}
+function isInlineSafeMimeType(contentType) {
+  return INLINE_SAFE_MIME_TYPES.has(normalizeMimeType(contentType));
+}
+function isRemoteUri(uri) {
+  return /^https?:\/\//i.test(uri);
+}
+function isBlockedHost(hostname) {
+  let host = hostname.trim().toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) {
+    host = host.slice(1, -1);
+  }
+  host = host.replace(/\.+$/, "");
+  if (host === "" || host === "localhost" || host.endsWith(".localhost")) {
+    return true;
+  }
+  if (host === "169.254.169.254" || host === "metadata.google.internal" || host === "metadata" || host === "100.100.100.200") {
+    return true;
+  }
+  const ipv4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4) {
+    const octets = ipv4.slice(1).map((o) => Number(o));
+    if (octets.some((o) => o > 255)) return true;
+    return isBlockedIpv4(octets);
+  }
+  if (host.includes(":")) {
+    return isBlockedIpv6(host);
+  }
+  return false;
+}
+function isBlockedIpv4(octets) {
+  const [a, b] = octets;
+  if (a === 0) return true;
+  if (a === 10) return true;
+  if (a === 127) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function expandIpv6(host) {
+  let h = host.toLowerCase();
+  const pct = h.indexOf("%");
+  if (pct !== -1) h = h.slice(0, pct);
+  let tailHextets = [];
+  const lastColon = h.lastIndexOf(":");
+  const tail = lastColon === -1 ? "" : h.slice(lastColon + 1);
+  if (tail.includes(".")) {
+    const m = tail.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m) return null;
+    const octets = m.slice(1).map((o) => Number(o));
+    if (octets.some((o) => o > 255)) return null;
+    tailHextets = [octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]];
+    h = h.slice(0, lastColon);
+    if (h === ":") h = "::";
+  }
+  const parseHextets = (parts) => {
+    const out = [];
+    for (const p of parts) {
+      if (p === "" || !/^[0-9a-f]{1,4}$/.test(p)) return null;
+      out.push(Number.parseInt(p, 16));
+    }
+    return out;
+  };
+  const doubleColon = h.indexOf("::");
+  let head;
+  let midTail;
+  if (doubleColon !== -1) {
+    if (h.indexOf("::", doubleColon + 1) !== -1) return null;
+    const before = h.slice(0, doubleColon);
+    const after = h.slice(doubleColon + 2);
+    head = parseHextets(before === "" ? [] : before.split(":"));
+    midTail = parseHextets(after === "" ? [] : after.split(":"));
+  } else {
+    head = parseHextets(h === "" ? [] : h.split(":"));
+    midTail = [];
+  }
+  if (head === null || midTail === null) return null;
+  const explicit = [...head, ...midTail, ...tailHextets];
+  if (doubleColon !== -1) {
+    if (explicit.length > 7) return null;
+    const fill = 8 - explicit.length;
+    return [...head, ...new Array(fill).fill(0), ...midTail, ...tailHextets];
+  }
+  if (explicit.length !== 8) return null;
+  return explicit;
+}
+function isBlockedIpv6(host) {
+  const hextets = expandIpv6(host);
+  if (hextets === null) return true;
+  const [h0, h1, h2, h3, h4, h5, h6, h7] = hextets;
+  const embeddedV4 = () => [
+    h6 >> 8 & 255,
+    h6 & 255,
+    h7 >> 8 & 255,
+    h7 & 255
+  ];
+  if (h0 === 0 && h1 === 0 && h2 === 0 && h3 === 0 && h4 === 0 && h5 === 0) {
+    if (h6 === 0 && h7 === 0) return true;
+    if (h6 === 0 && h7 === 1) return true;
+    return isBlockedIpv4(embeddedV4());
+  }
+  if (h0 === 0 && h1 === 0 && h2 === 0 && h3 === 0 && h4 === 0 && h5 === 65535) {
+    return isBlockedIpv4(embeddedV4());
+  }
+  if ((h0 & 65472) === 65152) return true;
+  if ((h0 & 65472) === 65216) return true;
+  if ((h0 & 65024) === 64512) return true;
+  if ((h0 & 65280) === 65280) return true;
+  return false;
+}
+function assertSafeRemoteUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new AssetServeError("Invalid remote asset URL", 502);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new AssetServeError("Unsupported remote asset scheme", 502);
+  }
+  if (isBlockedHost(url.hostname)) {
+    throw new AssetServeError("Remote asset host not allowed", 502);
+  }
+  return url;
+}
+async function fetchRemoteAsset(startUrl, fetchImpl, maxBytes, timeoutMs) {
+  let current = assertSafeRemoteUrl(startUrl);
+  for (let hop = 0; hop <= MAX_REMOTE_REDIRECTS; hop++) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(current.toString(), {
+        redirect: "manual",
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (!location) {
+        throw new AssetServeError(
+          "Remote asset redirect missing Location",
+          502
+        );
+      }
+      current = assertSafeRemoteUrl(new URL(location, current).toString());
+      continue;
+    }
+    if (!response.ok) {
+      throw new AssetServeError(
+        `Remote asset upstream returned ${response.status}`,
+        502
+      );
+    }
+    const data = await readBodyWithCap(response, maxBytes);
+    return {
+      data,
+      contentType: response.headers.get("content-type") ?? void 0
+    };
+  }
+  throw new AssetServeError("Too many remote asset redirects", 502);
+}
+async function readBodyWithCap(response, maxBytes) {
+  const declared = response.headers.get("content-length");
+  if (declared && Number(declared) > maxBytes) {
+    throw new AssetServeError("Remote asset exceeds size limit", 502);
+  }
+  const body = response.body;
+  if (body && typeof body.getReader === "function") {
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        total += value.byteLength;
+        if (total > maxBytes) {
+          await reader.cancel().catch(() => {
+          });
+          throw new AssetServeError("Remote asset exceeds size limit", 502);
+        }
+        chunks.push(value);
+      }
+    }
+    return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+  }
+  const buf = Buffer.from(await response.arrayBuffer());
+  if (buf.byteLength > maxBytes) {
+    throw new AssetServeError("Remote asset exceeds size limit", 502);
+  }
+  return buf;
+}
+async function resolveAssetForServing(options) {
+  const {
+    runtime,
+    asset: assetOrId,
+    tenantId: tenantId2,
+    canAccess,
+    disposition: _disposition
+  } = options;
+  const asset = typeof assetOrId === "string" ? await runtime.collection.get({ id: assetOrId }) : assetOrId;
+  if (!asset) {
+    throw new AssetServeError("Asset not found", 404);
+  }
+  if (tenantId2 !== void 0 && asset.tenantId !== null && asset.tenantId !== tenantId2) {
+    throw new AssetServeError("Asset not visible to this tenant", 403);
+  }
+  if (canAccess) {
+    const allowed = await canAccess(asset);
+    if (!allowed) {
+      throw new AssetServeError("Asset access denied", 403);
+    }
+  }
+  const remoteMode = options.remoteMode ?? "error";
+  let data;
+  let remoteContentType;
+  if (isRemoteUri(asset.sourceUri)) {
+    if (remoteMode === "error") {
+      throw new AssetServeError("Remote asset not supported", 500);
+    }
+    if (remoteMode === "redirect") {
+      throw new RedirectToSourceUri(asset.sourceUri);
+    }
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+      throw new AssetServeError(
+        "No fetch implementation available for remote asset",
+        500
+      );
+    }
+    const maxBytes = options.remoteMaxBytes ?? DEFAULT_REMOTE_MAX_BYTES;
+    const timeoutMs = options.remoteTimeoutMs ?? DEFAULT_REMOTE_TIMEOUT_MS;
+    try {
+      const result = await fetchRemoteAsset(
+        asset.sourceUri,
+        fetchImpl,
+        maxBytes,
+        timeoutMs
+      );
+      data = result.data;
+      remoteContentType = result.contentType;
+    } catch (err) {
+      if (err instanceof AssetServeError) throw err;
+      console.error("serveAsset: remote fetch failed", err);
+      throw new AssetServeError("Failed to fetch remote asset", 502);
+    }
+  } else {
+    try {
+      data = await runtime.store.read(asset);
+    } catch (err) {
+      console.error("serveAsset: store read failed", err);
+      throw new AssetServeError(
+        "Failed to read asset bytes",
+        500,
+        "Failed to read asset bytes"
+      );
+    }
+  }
+  const contentType = asset.mimeType || remoteContentType || "application/octet-stream";
+  const filename = options.filename ?? deriveFilename(asset);
+  return {
+    asset,
+    data,
+    contentType,
+    filename,
+    size: data.byteLength
+  };
+}
+class RedirectToSourceUri extends Error {
+  constructor(location) {
+    super("Asset stored at remote URL");
+    this.location = location;
+    this.name = "RedirectToSourceUri";
+  }
+  location;
+}
+async function serveAsset(options) {
+  const Ctor = options.responseCtor ?? globalThis.Response;
+  if (!Ctor) {
+    throw new Error(
+      "serveAsset: no Response constructor available. Pass options.responseCtor or run on Node 18+."
+    );
+  }
+  try {
+    const { data, contentType, filename, size } = await resolveAssetForServing(options);
+    const requestedDisposition = options.disposition ?? "inline";
+    const disposition = requestedDisposition === "attachment" || isInlineSafeMimeType(contentType) ? requestedDisposition : "attachment";
+    const PROTECTED_HEADERS = /* @__PURE__ */ new Set([
+      "content-type",
+      "content-length",
+      "content-disposition",
+      "x-content-type-options"
+    ]);
+    const headers = {};
+    for (const [name, value] of Object.entries(options.headers ?? {})) {
+      if (!PROTECTED_HEADERS.has(name.toLowerCase())) {
+        headers[name] = value;
+      }
+    }
+    headers["Content-Type"] = contentType;
+    headers["Content-Length"] = String(size);
+    headers["Content-Disposition"] = buildContentDisposition(
+      disposition,
+      filename
+    );
+    headers["X-Content-Type-Options"] = "nosniff";
+    return new Ctor(
+      data,
+      {
+        status: 200,
+        headers
+      }
+    );
+  } catch (err) {
+    if (err instanceof RedirectToSourceUri) {
+      return new Ctor(null, {
+        status: 302,
+        headers: { Location: err.location }
+      });
+    }
+    if (err instanceof AssetServeError) {
+      if (err.status >= 500) {
+        console.error("serveAsset: request failed", err.status, err.message);
+      }
+      return new Ctor(err.clientMessage, {
+        status: err.status,
+        headers: { "Content-Type": "text/plain; charset=utf-8" }
+      });
+    }
+    console.error("serveAsset: unexpected error", err);
+    return new Ctor("Internal error serving asset", {
+      status: 500,
+      headers: { "Content-Type": "text/plain; charset=utf-8" }
+    });
+  }
+}
+function defaultClientMessage(status) {
+  switch (status) {
+    case 403:
+      return "Forbidden";
+    case 404:
+      return "Not found";
+    case 502:
+      return "Bad gateway";
+    default:
+      return "Internal error serving asset";
+  }
+}
+class AssetServeError extends Error {
+  constructor(message, status, clientMessage) {
+    super(message);
+    this.status = status;
+    this.name = "AssetServeError";
+    this.clientMessage = clientMessage ?? defaultClientMessage(status);
+  }
+  status;
+  /** Opaque body safe to return to the HTTP client. */
+  clientMessage;
+}
+function deriveFilename(asset) {
+  if (asset.name) return asset.name;
+  const fromUri = extractBasename(asset.sourceUri);
+  if (fromUri) return fromUri;
+  return asset.id ?? "asset";
+}
+function extractBasename(uri) {
+  if (!uri) return "";
+  const noScheme = uri.replace(/^[a-z][a-z0-9+\-.]*:\/\//i, "");
+  const last = noScheme.split("/").pop() ?? "";
+  return last;
+}
+function sanitizeDispositionFilename(filename) {
+  let stripped = "";
+  for (const ch of filename) {
+    const code = ch.charCodeAt(0);
+    if (code > 31 && code !== 127) {
+      stripped += ch;
+    }
+  }
+  const safe = stripped.replace(/["\\/]/g, "_").trim();
+  return safe || "asset";
+}
+function buildContentDisposition(disposition, filename) {
+  const sanitized = sanitizeDispositionFilename(filename);
+  const encoded = encodeURIComponent(sanitized);
+  return `${disposition}; filename="${sanitized}"; filename*=UTF-8''${encoded}`;
+}
+class AssetStatusCollection extends SmrtCollection {
+  static _itemClass = AssetStatus;
+  /**
+   * Get or create an asset status by slug
+   *
+   * @param slug - The asset status slug
+   * @param name - The display name (defaults to slug)
+   * @param description - Optional description
+   * @returns The existing or newly created AssetStatus
+   */
+  async getOrCreate(slug, name, description) {
+    const existing = await this.list({ where: { slug }, limit: 1 });
+    if (existing.length > 0) {
+      return existing[0];
+    }
+    return await this.create({
+      slug,
+      name: name || slug,
+      description
+    });
+  }
+  /**
+   * Initialize common asset statuses
+   *
+   * Creates standard asset statuses if they don't exist:
+   * - draft
+   * - published
+   * - archived
+   * - deleted
+   */
+  async initializeCommonStatuses() {
+    await this.getOrCreate("draft", "Draft", "Work in progress, not yet ready");
+    await this.getOrCreate("published", "Published", "Live and available");
+    await this.getOrCreate(
+      "archived",
+      "Archived",
+      "No longer active but preserved"
+    );
+    await this.getOrCreate("deleted", "Deleted", "Marked for deletion");
+  }
+}
+class AssetTypeCollection extends SmrtCollection {
+  static _itemClass = AssetType;
+  /**
+   * Get or create an asset type by slug
+   *
+   * @param slug - The asset type slug
+   * @param name - The display name (defaults to slug)
+   * @param description - Optional description
+   * @returns The existing or newly created AssetType
+   */
+  async getOrCreate(slug, name, description) {
+    const existing = await this.list({ where: { slug }, limit: 1 });
+    if (existing.length > 0) {
+      return existing[0];
+    }
+    return await this.create({
+      slug,
+      name: name || slug,
+      description
+    });
+  }
+  /**
+   * Initialize common asset types
+   *
+   * Creates standard asset types if they don't exist:
+   * - image
+   * - video
+   * - document
+   * - audio
+   *
+   * Note: `folder` was removed in R3-D. Folders are no longer an asset
+   * subtype — they live on their own `folders` table. See `folder.ts`.
+   */
+  async initializeCommonTypes() {
+    await this.getOrCreate(
+      "image",
+      "Image",
+      "Image files (JPEG, PNG, GIF, etc.)"
+    );
+    await this.getOrCreate(
+      "video",
+      "Video",
+      "Video files (MP4, AVI, MOV, etc.)"
+    );
+    await this.getOrCreate(
+      "document",
+      "Document",
+      "Document files (PDF, DOCX, TXT, etc.)"
+    );
+    await this.getOrCreate(
+      "audio",
+      "Audio",
+      "Audio files (MP3, WAV, AAC, etc.)"
+    );
+  }
+}
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+let Folder = class extends SmrtHierarchical {
+  tenantId = null;
+  // Core fields. `parentId` is inherited from SmrtHierarchical.
+  name = "";
+  // `slug` is inherited as an accessor from SmrtObject.
+  description = "";
+  ownerProfileId = null;
+  // Timestamps
+  createdAt = /* @__PURE__ */ new Date();
+  updatedAt = /* @__PURE__ */ new Date();
+  constructor(options = {}) {
+    super(options);
+    if (options.name !== void 0) this.name = options.name;
+    if (options.slug !== void 0) this.slug = options.slug;
+    if (options.description !== void 0)
+      this.description = options.description;
+    if (options.parentId !== void 0)
+      this.parentId = options.parentId ?? null;
+    if (options.ownerProfileId !== void 0)
+      this.ownerProfileId = options.ownerProfileId;
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.createdAt) this.createdAt = options.createdAt;
+    if (options.updatedAt) this.updatedAt = options.updatedAt;
+  }
+  // Hierarchy traversal (getParent / getChildren / getAncestors /
+  // getDescendants / getHierarchy / moveTo) provided by SmrtHierarchical.
+  /**
+   * Look up a folder by slug.
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+__decorateClass([
+  tenantId({ nullable: true })
+], Folder.prototype, "tenantId", 2);
+__decorateClass([
+  crossPackageRef("@happyvertical/smrt-profiles:Profile")
+], Folder.prototype, "ownerProfileId", 2);
+Folder = __decorateClass([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create", "update"] },
+    cli: true
+  })
+], Folder);
+class FolderCollection extends SmrtCollection {
+  static _itemClass = Folder;
+  /**
+   * Get the folder tree starting from an optional root.
+   *
+   * When `rootId` is omitted, returns top-level folders (those with no
+   * parent). When `rootId` is provided, returns all descendants of that
+   * folder via the inherited SmrtHierarchical BFS traversal — same
+   * cycle-safe, one-query-per-depth behaviour as Place/Event.
+   *
+   * @param rootId - Optional root folder ID; if omitted, returns top-level folders
+   * @returns Array of folders (flat list; use parentId to reconstruct tree)
+   */
+  async getTree(rootId) {
+    if (!rootId) {
+      return await this.list({
+        where: { parentId: null },
+        orderBy: "name ASC"
+      });
+    }
+    const result = [];
+    const queue = [rootId];
+    const visited = /* @__PURE__ */ new Set([rootId]);
+    while (queue.length > 0) {
+      const currentId = queue.shift();
+      const children = await this.list({
+        where: { parentId: currentId },
+        orderBy: "name ASC"
+      });
+      for (const child of children) {
+        if (child.id && !visited.has(child.id)) {
+          visited.add(child.id);
+          result.push(child);
+          queue.push(child.id);
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Get the path from root to a given folder (ancestors + self).
+   *
+   * @param folderId - The folder ID to get the path for
+   * @returns Array of folders from root to the given folder (inclusive)
+   */
+  async getPath(folderId) {
+    const folder = await this.get({ id: folderId });
+    if (!folder) return [];
+    const ancestors = await folder.getAncestors();
+    return [...ancestors, folder];
+  }
+  /**
+   * Get all assets that are direct children of a folder.
+   *
+   * Folder membership is recorded on `Asset.folderId`, not on the folder
+   * itself, so this is delegated to the asset collection.
+   *
+   * @param folderId - The folder ID
+   * @param assetCollection - An AssetCollection instance for querying
+   * @returns Array of assets in this folder
+   */
+  async getContents(folderId, assetCollection) {
+    return await assetCollection.list({
+      where: { folderId }
+    });
+  }
+  /**
+   * Move an asset into a folder (or out, by passing `null`).
+   *
+   * @param asset - The asset to move
+   * @param folderId - The target folder ID (or null to move to root)
+   */
+  async moveAsset(asset, folderId) {
+    asset.folderId = folderId;
+    await asset.save();
+  }
+}
+async function persistMediaBundleInspection(adapter, inspection, options = {}) {
+  const warnings = [...inspection.warnings];
+  const primary = await adapter.upsertAsset({
+    file: inspection.primary,
+    role: "primary",
+    typeSlug: options.primaryTypeSlug,
+    metadata: inspection.metadata,
+    inspection
+  });
+  const supportAssetIds = [];
+  for (const support of inspection.supportFiles) {
+    const visibility = support.visibility ?? options.supportVisibility ?? "hidden-retained";
+    if (visibility === "drop-after-extract") continue;
+    const supportAsset = await adapter.upsertAsset({
+      file: support.file,
+      role: "support",
+      typeSlug: options.supportTypeSlug,
+      parentAssetId: primary.id,
+      relationship: support.relationship,
+      visibility,
+      metadata: support.metadata ?? {},
+      inspection
+    });
+    supportAssetIds.push(supportAsset.id);
+    await adapter.associateSupportFile?.({
+      primaryAssetId: primary.id,
+      supportAssetId: supportAsset.id,
+      relationship: support.relationship,
+      visibility,
+      metadata: support.metadata
+    });
+  }
+  let metadataArtifactId;
+  if (options.writeMetadataArtifact !== false && adapter.writeMetadataArtifact) {
+    const artifact = await adapter.writeMetadataArtifact({
+      primaryAssetId: primary.id,
+      inspection
+    });
+    metadataArtifactId = artifact?.id;
+  }
+  let gpsTrackPointCount = 0;
+  const gpsTrack = inspection.metadata.gpsTrack ?? [];
+  if (options.writeGpsTrack !== false && gpsTrack.length > 0) {
+    if (adapter.replaceGpsTrack) {
+      gpsTrackPointCount = await adapter.replaceGpsTrack(primary.id, gpsTrack);
+    } else {
+      warnings.push("adapter cannot persist gps track");
+    }
+  }
+  return {
+    primaryAssetId: primary.id,
+    supportAssetIds,
+    metadataArtifactId,
+    gpsTrackPointCount,
+    warnings
+  };
+}
+const OWNED_ASSET_RELATIONSHIP_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertValidOwnedAssetRelationship(relationship) {
+  if (!OWNED_ASSET_RELATIONSHIP_PATTERN.test(relationship)) {
+    throw new Error(
+      `Invalid relationship type "${relationship}"; must start with a letter or underscore and contain only letters, digits, and underscores`
+    );
+  }
+}
+function assertValidOwnedAssetSortOrder(sortOrder) {
+  if (!Number.isInteger(sortOrder) || sortOrder < 0 || sortOrder > 2147483647) {
+    throw new Error(
+      `Invalid sortOrder "${sortOrder}"; must be a non-negative integer`
+    );
+  }
+}
+async function resolveOwnedAssetsById(db, assetIds, tenantId2) {
+  if (assetIds.length === 0) {
+    return [];
+  }
+  const assets = await AssetCollection.create({ db });
+  const resolved = tenantId2 ? await withSystemContext(async () => assets.listByIds(assetIds)) : await assets.listByIds(assetIds);
+  const visibleAssets = tenantId2 ? resolved.filter(
+    (asset) => asset.tenantId === tenantId2 || asset.tenantId === null
+  ) : resolved;
+  const assetsById = new Map(
+    visibleAssets.filter((asset) => asset.id).map((asset) => [asset.id, asset])
+  );
+  return assetIds.map((assetId) => assetsById.get(assetId)).filter(Boolean);
+}
+async function getOwnerRecord(collection, ownerId) {
+  return collection.get({ id: ownerId });
+}
+async function getOwnedAssetsFromCollection(collection, ownerId, relationship) {
+  const owner = await getOwnerRecord(collection, ownerId);
+  if (!owner) {
+    return [];
+  }
+  return owner.getAssets(relationship);
+}
+async function addOwnedAssetFromCollection(collection, ownerType, ownerId, asset, relationship = "attachment", sortOrder = 0) {
+  const owner = await getOwnerRecord(collection, ownerId);
+  if (!owner) {
+    throw new Error(`${ownerType} '${ownerId}' not found`);
+  }
+  await owner.addAsset(asset, relationship, sortOrder);
+}
+async function removeOwnedAssetFromCollection(collection, ownerType, ownerId, assetId, relationship) {
+  const owner = await getOwnerRecord(collection, ownerId);
+  if (!owner) {
+    throw new Error(`${ownerType} '${ownerId}' not found`);
+  }
+  await owner.removeAsset(assetId, relationship);
+}
+export {
+  ASSET_EXTRACTION_STATUS,
+  ASSET_METADATA_KEYS,
+  ASSET_ROLES,
+  Asset,
+  AssetAssociation,
+  AssetAssociationCollection,
+  AssetCapabilitySkippedError,
+  AssetCapabilityUnavailableError,
+  AssetCollection,
+  AssetMetafield,
+  AssetMetafieldCollection,
+  AssetRuntime,
+  AssetServeError,
+  AssetStatus,
+  AssetStatusCollection,
+  AssetStore,
+  AssetType,
+  AssetTypeCollection,
+  Folder,
+  FolderCollection,
+  OWNED_ASSET_RELATIONSHIP_PATTERN,
+  addOwnedAssetFromCollection,
+  assertValidOwnedAssetRelationship,
+  assertValidOwnedAssetSortOrder,
+  createAssetRuntime,
+  getOwnedAssetsFromCollection,
+  persistMediaBundleInspection,
+  removeOwnedAssetFromCollection,
+  resolveAssetForServing,
+  resolveOwnedAssetsById,
+  serveAsset
+};
+//# sourceMappingURL=index.js.map