@spinekit/media 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 0.1.1 - 2026-08-21
+
+### Changed
+- **License:** relicensed from MIT to the **Classytic Source-Available License**
+  (Community & Commercial). Evaluation and development use remain free; production
+  use now requires a commercial license from Classytic LLC. See `LICENSE`.
+
+### Notes
+- First stable **1.0.0** release of the Classytic `arc` suite. Versions published
+  before 1.0.0 remain under their original MIT terms; the new license applies from
+  1.0.0 onward.
+
+## 0.2.1 — 2026-07-22
+
+- `ctxOf` now derives via arc 2.25's `scopeFirstCtx` (`orgHeader: false` keeps the scope-only org read; no fabricated actor — unauthenticated callers still yield no `userId`). Kills this package's copy of the per-package context-derivation clone (PACKAGE_RULES §4b.1). Peer floor: `@classytic/arc >=2.25.0`.
+
+## 0.2.0 — 2026-07-20
+
+- **scheduledJobs arm**: createMediaModule now wires mediaMaintenanceSchedules into arc's scheduledJobs arm (opt out with maintenance: false). Peer floor raised @classytic/arc >=2.24.0.
+- **BREAKING (names)**: schedule/lock names media-purge-* → canonical dotted media.purge.*.
+- **owns colocation (PACKAGE_RULES §1.5)**: createMediaModule now declares `ArcModule.owns: ['media']`, mirroring its single resource. Hosts remove their hand-maintained supersession lists.
+- Long-interval schedules set explicit leaseMs (~90% of every) — arc's default lease caps at 5min, which would let independently-phased replicas re-run hourly/daily sweeps.
+- Actor/org context now reads arc's RequestScope (getUserId/getOrgId from @classytic/arc/scope) instead of hand-rolled req.user/header reads. For Better-Auth-org hosts this is behavior-preserving AND closes an unvalidated-header org-spoof hole; hosts on auth.type 'custom'/'authenticator' (arc leaves req.scope PUBLIC) must populate scope or the ctx degrades to anonymous — see arc resolveOrgFromHeader for the migration path.
+
+## 0.1.0 — 2026-07-18
+
+Initial release.
+
+- `createMediaModule` / `createMediaResource` — `@classytic/media-kit` (>=3.7)
+  as one Arc resource: adapter-backed reads, kernel-verb-only writes.
+- Two-phase direct-to-storage flow: `POST /start-write` (presigned PUT or
+  multipart/resumable session by size/`partCount`), `POST /complete-write`
+  (storage-verified confirm + client display hints), `POST /sign-parts`,
+  `POST /complete-multipart`, `POST /abort-multipart` (ctx-guarded via
+  media-kit 3.7's tenant-aware abort — a leaked key+uploadId can't kill
+  another tenant's in-flight upload; pairs with react-media 0.4's
+  `createArcMediaProvider`).
+- Content-hash dedup handshake: `start-write` with `sha256` short-circuits on
+  a tenant-scoped hit — pairs with `@classytic/media-transform`'s `sha256Hex`.
+- `signed-url` action for time-boxed private reads.
+- `mediaMaintenanceSchedules(engine)` — stale-pending / soft-delete / expiry
+  sweeps as `ScheduleDefinition[]` for arc's `schedulesPlugin` (2.21).

package/LICENSE

@@ -0,0 +1,75 @@
+Classytic Source-Available License (Community & Commercial), Version 1.0
+
+Copyright (c) 2026 Classytic LLC. All rights reserved.
+
+This software is source-available, not open source. Please read this License
+before using it.
+
+1. DEFINITIONS
+   "Software" means the contents of this package and any accompanying source
+   code, object code, or documentation, in any form.
+   "Licensor" means Classytic LLC, a limited liability company organized in the
+   United States.
+   "You" means the individual or legal entity exercising rights under this
+   License.
+   "Evaluation Use" means use for evaluation, development, testing,
+   experimentation, or internal non-commercial purposes only.
+   "Production Use" means any use of the Software that is live, commercial,
+   revenue-generating, or customer-facing, or any use other than Evaluation Use.
+   "Commercial License" means a separate written agreement executed with
+   Licensor that grants Production Use rights.
+
+2. OWNERSHIP
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   All rights not expressly granted in this License are reserved by Licensor.
+
+3. EVALUATION GRANT
+   Subject to Your compliance with this License, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable, revocable license
+   to download, install, run, and modify the Software solely for Evaluation Use.
+
+4. PRODUCTION USE REQUIRES A COMMERCIAL LICENSE
+   Production Use of the Software is NOT permitted under this License and
+   requires a Commercial License from Licensor. A Commercial License may be
+   granted at Licensor's discretion, with or without a fee, and may confer
+   perpetual, irrevocable, and transferable Production Use rights as set out in
+   that agreement. Contact licensing@classytic.com to obtain one.
+
+5. RESTRICTIONS
+   You may not:
+   (a) make any Production Use of the Software without a Commercial License;
+   (b) redistribute, resell, rent, sublicense, or otherwise make the Software
+       (in whole or in part, original or modified) available to third parties as
+       a stand-alone product, framework, library, or hosted/managed service that
+       competes with the Software or with Licensor;
+   (c) remove, obscure, or alter any copyright, license, or attribution notice.
+
+6. FEEDBACK AND CONTRIBUTIONS
+   Any feedback, suggestions, or contributions You provide relating to the
+   Software may be used by Licensor for any purpose without obligation to You.
+
+7. TERMINATION
+   This License and the Evaluation Grant terminate automatically if You breach
+   any term. Upon termination You must cease all use of the Software and destroy
+   all copies in Your possession. Rights under a Commercial License are governed
+   by that agreement's own terms and survive termination of this License to the
+   extent stated there.
+
+8. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE
+   FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+10. GOVERNING LAW
+   This License is governed by the laws of the State of Delaware, United States,
+   without regard to its conflict-of-laws principles. (Adjust to Your LLC's state
+   of formation.)
+
+For commercial licensing, contact: licensing@classytic.com

package/README.md

@@ -0,0 +1,82 @@
+# @spinekit/media
+
+> Two-phase direct-to-storage uploads, content-hash dedup, and media registry — `@classytic/media-kit` as one composable Arc resource.
+
+The module every host otherwise hand-rolls around a blob store. Bytes never
+stream through your API server: `start-write` mints a presigned target (or a
+multipart/resumable session for big files), the client uploads straight to
+storage, and `complete-write` registers the asset **storage-verified** (the
+kernel re-checks exists/stat/MIME/tenant-bound key — client claims are never
+trusted). A client that sends a content hash (`@classytic/media-transform`'s
+`sha256Hex`) gets the dedup handshake: on a tenant-scoped hash hit, **no
+upload happens at all**.
+
+Direct wire `create`/`update` are disabled — the verified verbs are the only
+way bytes enter. `DELETE` respects the engine's soft-delete + storage cleanup.
+
+## Install
+
+```sh
+npm install @spinekit/media @classytic/media-kit @classytic/arc @classytic/mongokit mongoose
+```
+
+Peers: `@classytic/arc >=2.21.0` · `@classytic/media-kit >=3.6.0` ·
+`@classytic/mongokit >=3.21.0` · `mongoose >=9.4.1`.
+
+## Usage
+
+```ts
+import { createApp } from '@classytic/arc/factory';
+import { schedulesPlugin } from '@classytic/arc/plugins';
+import { requireAuth, requireRoles } from '@classytic/arc/permissions';
+import { createMedia } from '@classytic/media-kit';
+import { createS3Provider } from '@classytic/media-kit/providers/s3';
+import { createMediaModule, mediaMaintenanceSchedules } from '@spinekit/media';
+
+const engine = await createMedia({ connection, driver: createS3Provider({ /* ... */ }) });
+
+const app = await createApp({
+  modules: [
+    createMediaModule({
+      engine,
+      permissions: {
+        view: requireAuth(),
+        upload: requireAuth(),
+        manage: requireRoles(['admin']),
+      },
+    }),
+  ],
+  plugins: async (f) => {
+    await f.register(schedulesPlugin, {
+      // lock: createMongoLockAdapter({ connection }) — for multi-replica
+      schedules: mediaMaintenanceSchedules(engine),
+    });
+  },
+});
+```
+
+## Surface
+
+| Route | What |
+|---|---|
+| `POST /media/start-write` | Dedup short-circuit (`sha256`) → else presigned PUT → else multipart/resumable session (`multipart`/`partCount`/size ≥ threshold) |
+| `POST /media/complete-write` | Confirm a presigned upload; stores client display hints (`thumbhash`, `dominantColor`, `width`, `height`) |
+| `POST /media/sign-parts` | On-demand part URLs for an open multipart session |
+| `POST /media/complete-multipart` | Assemble parts, register the asset |
+| `POST /media/:id/action` `{ action: 'signed-url' }` | Time-boxed signed read URL (needs engine `signing` config) |
+| `GET /media`, `GET /media/:id` | Adapter reads (QueryParser filters: status, mimeType, folder, visibility, hash, filename, tags) |
+| `DELETE /media/:id` | Kernel delete (soft per engine config, storage cleanup) |
+
+`mediaMaintenanceSchedules(engine)` returns `ScheduleDefinition[]` for arc's
+`schedulesPlugin` — stale-pending (hourly), soft-delete purge (daily), and
+expiry purge (hourly) sweeps; pass a `lock` for multi-replica leader safety.
+Abandoned uploads that never reached `complete-write` leave unregistered
+storage keys — keep bucket lifecycle rules on as belt-and-braces.
+
+The engine is exported at `fastify.arc.modules.media`. Host seams (extra
+routes/actions, cache, field rules) inject via `seams:` — arc 2.21
+`mergeResourceConfig` semantics.
+
+## License
+
+MIT © Classytic

package/dist/attachments.d.mts

@@ -0,0 +1,66 @@
+import { MediaContext, MediaEngine } from "@classytic/media-kit";
+//#region src/attachments.d.ts
+interface BoundMediaRef {
+  sourceModel: string;
+  sourceId: string;
+}
+interface BoundMediaStorage<TTarget, TContext> {
+  upload(input: {
+    target: TTarget;
+    buffer: Buffer;
+    filename: string;
+    mimeType: string;
+  }, context: TContext): Promise<BoundMediaRef>;
+  startWrite(input: {
+    target: TTarget;
+    filename: string;
+    contentType: string;
+    size: number;
+  }, context: TContext): Promise<{
+    kind: 'presigned';
+    upload: {
+      uploadUrl: string;
+      key: string;
+      headers?: Record<string, string>;
+    };
+  }>;
+  completeWrite(input: {
+    target: TTarget;
+    key: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+  }, context: TContext): Promise<BoundMediaRef>;
+  signedUrl(input: {
+    target: TTarget;
+    mediaRef: BoundMediaRef;
+    expiresIn: number;
+  }, context: TContext): Promise<string>;
+  discard(mediaRef: BoundMediaRef, context: TContext): Promise<void>;
+  listOrphans(input: {
+    olderThan: Date;
+    limit: number;
+  }): Promise<readonly {
+    mediaRef: BoundMediaRef;
+    organizationId?: string;
+  }[]>;
+}
+interface BoundMediaStorageOptions<TTarget, TContext> {
+  engine(): Pick<MediaEngine, 'models' | 'repositories'>;
+  folderFor(target: TTarget): string;
+  contextFor(context: TContext): MediaContext;
+  /** Folder roots owned by this attachment domain, without a trailing wildcard. */
+  orphanFolderPrefixes: readonly [string, ...string[]];
+  /** Storage visibility stamped at verified completion. Default `private`. */
+  visibility?: 'public' | 'private';
+}
+/**
+ * Universal verified-storage adapter for domain attachments.
+ *
+ * The consuming domain owns target authorization. This adapter owns every
+ * MediaKit concern: server-derived folders, presign/confirm, signed reads,
+ * compensation and orphan enumeration.
+ */
+declare function createBoundMediaStorage<TTarget, TContext>(options: BoundMediaStorageOptions<TTarget, TContext>): BoundMediaStorage<TTarget, TContext>;
+//#endregion
+export { BoundMediaRef, BoundMediaStorage, BoundMediaStorageOptions, createBoundMediaStorage };

package/dist/attachments.mjs

@@ -0,0 +1,118 @@
+//#region src/attachments.ts
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function assertOwnedModel(engine, mediaRef) {
+	if (mediaRef.sourceModel !== engine.models.Media.modelName) throw Object.assign(/* @__PURE__ */ new Error("Media reference belongs to a different storage model"), {
+		status: 422,
+		code: "media.attachment.model_mismatch"
+	});
+}
+/**
+* Universal verified-storage adapter for domain attachments.
+*
+* The consuming domain owns target authorization. This adapter owns every
+* MediaKit concern: server-derived folders, presign/confirm, signed reads,
+* compensation and orphan enumeration.
+*/
+function createBoundMediaStorage(options) {
+	const folderPattern = `^(?:${options.orphanFolderPrefixes.map((prefix) => escapeRegex(prefix.replace(/\/+$/, ""))).join("|")})/`;
+	return {
+		async upload({ target, buffer, filename, mimeType }, context) {
+			const engine = options.engine();
+			const folder = options.folderFor(target);
+			const mediaContext = options.contextFor(context);
+			const media = await engine.repositories.media.upload({
+				buffer,
+				filename,
+				mimeType,
+				folder
+			}, mediaContext);
+			if (media.folder !== folder) {
+				await engine.repositories.media.hardDelete(String(media._id), mediaContext);
+				throw Object.assign(/* @__PURE__ */ new Error("Uploaded media is outside its attachment folder"), {
+					status: 422,
+					code: "media.attachment.folder_mismatch"
+				});
+			}
+			return {
+				sourceModel: engine.models.Media.modelName,
+				sourceId: String(media._id)
+			};
+		},
+		async startWrite({ target, filename, contentType, size }, context) {
+			return {
+				kind: "presigned",
+				upload: await options.engine().repositories.media.getSignedUploadUrl(filename, contentType, {
+					folder: options.folderFor(target),
+					size
+				}, options.contextFor(context))
+			};
+		},
+		async completeWrite({ target, key, filename, mimeType, size }, context) {
+			const engine = options.engine();
+			const mediaContext = options.contextFor(context);
+			const folder = options.folderFor(target);
+			const media = await engine.repositories.media.confirmUpload({
+				key,
+				filename,
+				originalFilename: filename,
+				mimeType,
+				size,
+				folder,
+				hashStrategy: "etag",
+				visibility: options.visibility ?? "private"
+			}, mediaContext);
+			if (media.folder !== folder) {
+				await engine.repositories.media.hardDelete(String(media._id), mediaContext);
+				throw Object.assign(/* @__PURE__ */ new Error("Confirmed media is outside its attachment folder"), {
+					status: 422,
+					code: "media.attachment.folder_mismatch"
+				});
+			}
+			return {
+				sourceModel: engine.models.Media.modelName,
+				sourceId: String(media._id)
+			};
+		},
+		async signedUrl({ target, mediaRef, expiresIn }, context) {
+			const engine = options.engine();
+			assertOwnedModel(engine, mediaRef);
+			const mediaContext = options.contextFor(context);
+			const media = await engine.repositories.media.getById(mediaRef.sourceId, {
+				...mediaContext.organizationId !== void 0 ? { organizationId: mediaContext.organizationId } : {},
+				...mediaContext.actorId !== void 0 ? { actorId: mediaContext.actorId } : {},
+				...mediaContext.session !== void 0 ? { session: mediaContext.session } : {}
+			});
+			if (!media || media.folder !== options.folderFor(target)) throw Object.assign(/* @__PURE__ */ new Error("Media is not attached to this target"), {
+				status: 403,
+				code: "media.attachment.access_denied"
+			});
+			return engine.repositories.media.getSignedAssetUrl(media, { expiresIn }, mediaContext);
+		},
+		async discard(mediaRef, context) {
+			const engine = options.engine();
+			assertOwnedModel(engine, mediaRef);
+			await engine.repositories.media.hardDelete(mediaRef.sourceId, options.contextFor(context));
+		},
+		async listOrphans({ olderThan, limit }) {
+			const engine = options.engine();
+			return (await engine.repositories.media.findAll({
+				folder: { $regex: folderPattern },
+				status: "ready",
+				createdAt: { $lt: olderThan }
+			}, {
+				limit,
+				sort: { createdAt: 1 }
+			})).map((media) => ({
+				mediaRef: {
+					sourceModel: engine.models.Media.modelName,
+					sourceId: String(media._id)
+				},
+				...media.organizationId ? { organizationId: String(media.organizationId) } : {}
+			}));
+		}
+	};
+}
+//#endregion
+export { createBoundMediaStorage };

package/dist/config/media.config.d.mts

@@ -0,0 +1,96 @@
+import { AspectRatioPreset, MediaRuntime, MediaShape, MediaSigningConfig, SizeVariant, StorageDriver } from "@classytic/media-kit";
+import { Connection } from "mongoose";
+//#region src/config/media.config.d.ts
+/** Cache windows, in seconds. `false` disables the cache plugin entirely. */
+interface MediaCacheOptions {
+  /** Fresh window for reads (mongokit `staleTime`). Default 60. */
+  staleTime?: number;
+  /** Retention past stale (mongokit `gcTime`). Default 60. */
+  gcTime?: number;
+  /** Fresh window for `getById` specifically — hot and rarely mutated. Default 300. */
+  getByIdStaleTime?: number;
+}
+interface MediaShapeInput {
+  /**
+   * Namespaces this company's objects inside a bucket shared across companies.
+   * Prefixes the storage KEY only — the content-type map and folder browser
+   * stay on bare folder names.
+   */
+  keyPrefix?: string | undefined;
+  /** Folder assumed when an upload names none. Default `'general'`. */
+  defaultFolder?: string;
+  /**
+   * Branch-scope the library. Default `false` — see the docblock; `true` makes
+   * media-kit apply the multi-tenant plugin so reads filter by `organizationId`.
+   */
+  tenant?: boolean;
+  /** Disable image derivatives when originals are evidence and must remain byte-exact. */
+  processingEnabled?: boolean;
+  /** Disable cross-record content deduplication when each upload is a distinct record. */
+  deduplicationEnabled?: boolean;
+  /** Default visibility for new assets. Legal/document stores should use `private`. */
+  defaultVisibility?: 'public' | 'private';
+  /** Enable time-boxed URLs for private assets. The matching serve route is mounted by Spine Media. */
+  signing?: MediaSigningConfig;
+  /**
+   * Replace an already-registered `Media` model instead of refusing.
+   *
+   * Mongoose locks a schema on the first `model()` call, so mongokit REFUSES a
+   * second registration rather than silently dropping whatever this one adds.
+   * That is right for production and wrong for a suite that boots the app twice
+   * on one connection: the second boot failed with a model collision, several
+   * layers from the cause. Every other engine in the fleet already exposes this
+   * (`process.env.NODE_ENV === 'test'`); media was the one that did not, so a
+   * host had no way to express it at all.
+   */
+  forceRecreate?: boolean;
+  /** Per-deployment overrides of the tuned defaults. */
+  overrides?: {
+    allowedMimeTypes?: readonly string[];
+    maxSize?: number;
+    maxWidth?: number;
+    aspectRatios?: Record<string, AspectRatioPreset>;
+    sizes?: readonly SizeVariant[];
+  };
+}
+/**
+ * The SHAPE — describe-time only (STANDARDIZATION-PLAN §6.2).
+ *
+ * What the media collection LOOKS like: which file types, which folders, which
+ * derivatives. Nothing here opens a connection, reaches a bucket or builds a
+ * cache; those are runtime and travel through `createMediaRuntime`.
+ *
+ * The split is not cosmetic. `driver` and `plugins` used to sit in this object,
+ * so producing a config meant constructing a storage client — describing the
+ * catalogue of image sizes performed I/O.
+ */
+declare function createMediaShape(input?: MediaShapeInput): MediaShape;
+/**
+ * The RUNTIME — bind-time collaborators.
+ *
+ * The driver talks to object storage and the cache plugin allocates; both are
+ * live systems, so they are built when the Spine module calls `bind()`.
+ */
+declare function createMediaRuntime(input: MediaRuntimeInput): MediaRuntime;
+interface MediaRuntimeInput {
+  /** Resolved storage driver (see `resolveMediaProvider`). */
+  driver: StorageDriver;
+  /** Shared event transport, when the deployment has one. */
+  eventTransport?: MediaRuntime['eventTransport'];
+  /** Cache tuning, or `false` to run without the cache plugin. */
+  cache?: MediaCacheOptions | false;
+}
+interface MediaBlueprintSourceInput {
+  connection: Connection;
+  shape?: MediaShapeInput;
+  runtime: MediaRuntimeInput | (() => MediaRuntimeInput | Promise<MediaRuntimeInput>);
+}
+/** Build a blueprint source inside Spine Media's package lineage for file-linked hosts. */
+declare function createMediaBlueprintSource(input: MediaBlueprintSourceInput): {
+  kind: 'blueprint';
+  blueprint: import("@classytic/media-kit").MediaBlueprint;
+  connection: Connection;
+  runtime: () => Promise<MediaRuntime>;
+};
+//#endregion
+export { MediaBlueprintSourceInput, MediaCacheOptions, MediaRuntimeInput, MediaShapeInput, createMediaBlueprintSource, createMediaRuntime, createMediaShape };

package/dist/config/media.config.mjs

@@ -0,0 +1,82 @@
+import { ASPECT_RATIO_PRESETS, FOLDER_CONTENT_TYPE_MAP, IMAGE_SETTINGS, SIZE_VARIANTS } from "./media.defaults.mjs";
+import { cachePlugin, createMemoryCache } from "@classytic/mongokit";
+import { defineMedia } from "@classytic/media-kit";
+//#region src/config/media.config.ts
+/**
+* The SHAPE — describe-time only (STANDARDIZATION-PLAN §6.2).
+*
+* What the media collection LOOKS like: which file types, which folders, which
+* derivatives. Nothing here opens a connection, reaches a bucket or builds a
+* cache; those are runtime and travel through `createMediaRuntime`.
+*
+* The split is not cosmetic. `driver` and `plugins` used to sit in this object,
+* so producing a config meant constructing a storage client — describing the
+* catalogue of image sizes performed I/O.
+*/
+function createMediaShape(input = {}) {
+	const o = input.overrides ?? {};
+	return {
+		tenant: input.tenant ?? false,
+		...input.forceRecreate !== void 0 ? { forceRecreate: input.forceRecreate } : {},
+		fileTypes: {
+			allowed: [...o.allowedMimeTypes ?? IMAGE_SETTINGS.allowedMimeTypes],
+			maxSize: o.maxSize ?? IMAGE_SETTINGS.maxSize
+		},
+		folders: {
+			defaultFolder: input.defaultFolder ?? "general",
+			...input.keyPrefix ? { keyPrefix: input.keyPrefix } : {},
+			contentTypeMap: Object.fromEntries(Object.entries(FOLDER_CONTENT_TYPE_MAP).map(([folder, types]) => [folder, [...types]]))
+		},
+		processing: {
+			enabled: input.processingEnabled ?? true,
+			maxWidth: o.maxWidth ?? IMAGE_SETTINGS.defaultMaxWidth,
+			quality: IMAGE_SETTINGS.quality,
+			format: IMAGE_SETTINGS.format,
+			aspectRatios: o.aspectRatios ?? ASPECT_RATIO_PRESETS,
+			sizes: [...o.sizes ?? SIZE_VARIANTS],
+			generateAlt: IMAGE_SETTINGS.generateAlt,
+			thumbhash: true,
+			dominantColor: true,
+			smartSkip: true
+		},
+		deduplication: {
+			enabled: input.deduplicationEnabled ?? true,
+			returnExisting: input.deduplicationEnabled ?? true,
+			algorithm: "sha256"
+		},
+		visibility: { default: input.defaultVisibility ?? "public" },
+		...input.signing ? { signing: input.signing } : {}
+	};
+}
+/**
+* The RUNTIME — bind-time collaborators.
+*
+* The driver talks to object storage and the cache plugin allocates; both are
+* live systems, so they are built when the Spine module calls `bind()`.
+*/
+function createMediaRuntime(input) {
+	const cache = input.cache === false ? {} : input.cache ?? {};
+	return {
+		driver: input.driver,
+		...input.eventTransport ? { eventTransport: input.eventTransport } : {},
+		plugins: input.cache === false ? [] : [cachePlugin({
+			adapter: createMemoryCache(),
+			defaults: {
+				staleTime: cache.staleTime ?? 60,
+				gcTime: cache.gcTime ?? 60
+			},
+			perOpDefaults: { getById: { staleTime: cache.getByIdStaleTime ?? 300 } }
+		})]
+	};
+}
+/** Build a blueprint source inside Spine Media's package lineage for file-linked hosts. */
+function createMediaBlueprintSource(input) {
+	return {
+		kind: "blueprint",
+		blueprint: defineMedia(createMediaShape(input.shape)),
+		connection: input.connection,
+		runtime: async () => createMediaRuntime(typeof input.runtime === "function" ? await input.runtime() : input.runtime)
+	};
+}
+//#endregion
+export { createMediaBlueprintSource, createMediaRuntime, createMediaShape };