cursedbelt 2.8.0 → 3.0.0

package/src/server/services/assetService.ts

@@ -1,734 +0,0 @@
-/**
- * `AssetService` over the media repositories and the `ObjectStore` (02 §1.1).
- *
- * The whole file exists to make one property true by construction: **the public
- * bytes route cannot serve a private item.** The audit's §4.3 finding was that
- * `/api/asset/items/:id/bytes` sits behind a plain session with no private-scope
- * requirement, so whether private bytes leak depends entirely on the service
- * re-checking the flag — and the mixin cannot tell a private id from a public
- * one. Here, `read` calls `readPublicMediaFile`, whose SQL carries
- * `encryption IS NULL`. There is no branch to forget: the private row is not in
- * the result set.
- *
- * Two further laws:
- *
- *   * **`revealPrivate` is decided from the verified session**, never from a
- *     client flag — a locked listing contains zero private items (04 V7.2).
- *   * **Bytes never round-trip through RAM.** `ObjectStore` deals in streams, so
- *     a 4GB video is a pipe, not a buffer (01 §2.5).
- */
-import { MEDIA_SOURCE_KINDS, type MediaSourceKind } from 'cwip/domains';
-import {
-  catalogueMediaFile,
-  readHlsRendition,
-  readPublicMediaFile,
-  type RepoScope,
-  scopedExec,
-  vaultRepo,
-} from 'cwip/repositories';
-import type { DomainHandle, ObjectStore, RepoOp, StorageProvider } from 'cwip/storage';
-import type { TelemetryWriter } from 'cwip/telemetry';
-import type { JobBroker } from '../drivers';
-import { AppError } from '../errors';
-import { createHash } from 'node:crypto';
-import type {
-  AlbumAssetView,
-  AlbumService,
-  AlbumView,
-  AssetService,
-  CallScope,
-  MediaItemView,
-  Page,
-  VaultAssetView,
-  VaultUploadResultView,
-  SourceService,
-  SourceView,
-  VaultUploadStatusView,
-} from '../mixins/services';
-import { type AssetItem, type AssetSource, createCatalogueMediaSource } from './assetSources';
-
-/** Job kind `requestOcr` enqueues; its output feeds `knowledge` via CDC. */
-export const ASSET_OCR_JOB = 'ocr';
-
-/**
- * Opens the bytes of a sealed (private) object. GuardEngine owns the key
- * material, so decryption is a seam rather than an import: this module must
- * never hold a master key.
- */
-export type PrivateBytesOpener = (
-  objectKey: string,
-  encryption: string,
-) => Promise<ReadableStream<Uint8Array> | null>;
-
-/**
- * The metric every stored byte is billed under (01 §4, 08 §5). Shared with the
- * `requireWithinPlan(ctx.enforcer, 'storage.bytes', …)` gate on the upload route
- * (11 §4) — the gate and the meter MUST name the same metric or the ceiling is
- * compared against a number nothing writes.
- */
-export const STORAGE_METRIC = 'storage.bytes';
-
-export interface AssetServiceOptions {
-  storage: StorageProvider;
-  objects: ObjectStore;
-  broker: JobBroker;
-  /**
-   * The durable meter (01 §4.1). REQUIRED, not optional: a file product that
-   * can be constructed without metering is a file product that will ship
-   * without metering, and every unmetered byte is a byte billed to nobody
-   * (08 §5 — "not a gap, a revenue leak").
-   */
-  telemetry: TelemetryWriter;
-  /**
-   * Verifier for URLs the LOCAL ObjectStore signed — normally
-   * `createFsObjectStore(...).verifySignedUrl`. Present ⇒ `readSignedObject`
-   * exists and the mixin mounts the object-serving route. Absent under saas,
-   * where the store presigns against the bucket and the app never sees the
-   * request.
-   */
-  verifySignedUrl?: (claim: { key: string; expiresAt: number; signature: string }) => boolean;
-  /**
-   * Required for the `privateMedia` feature. Absent ⇒ a private read fails LOUD
-   * (`PRIVATE_MEDIA_DECRYPTOR_MISSING`) rather than streaming ciphertext to a
-   * player that would render it as a corrupt file.
-   */
-  openPrivateBytes?: PrivateBytesOpener;
-  /** Id generator for catalogued uploads. */
-  mintId?: () => string;
-  /**
-   * Extra origins unioned into `list`/`read`/`remove` ON TOP of the always-present
-   * file catalogue (§2b). An asset instance with the vault effective passes
-   * `[createVaultMediaSource(storage)]` here, which is what lets AssetStudio
-   * replace Media Vault. The catalogue is always source[0]; these follow it.
-   */
-  sources?: readonly AssetSource[];
-  /**
-   * Reported when an object the vault meant to reclaim could not be deleted
-   * (05 §A2) — a dedupe's redundant copy, or a stranded upload the reaper found.
-   *
-   * A seam rather than a `console.warn`, because the consequence is a BILLING
-   * one: the object still occupies storage the meter no longer counts, so the
-   * tenant is charged for nothing and the drift compounds silently (law #6).
-   * The previous shape was `.catch(() => {})` — the failure had nowhere to go.
-   * Absent ⇒ the failure is swallowed, which is the caller's explicit choice
-   * rather than the library's default.
-   */
-  onOrphanedObject?(event: { objectKey: string; tenantId: string; cause: unknown }): void;
-}
-
-/**
- * How long a staging row may sit in `processing` before the reaper treats it as
- * abandoned. Deliberately generous: a slow client on a large file is a legitimate
- * `processing` row, and reaping a live upload deletes the object out from under
- * a stream that is still writing it.
- */
-export const VAULT_UPLOAD_STALE_MS = 6 * 60 * 60 * 1000;
-
-const scopeOf = (scope: CallScope): RepoScope => ({
-  tenantId: scope.claims.tenantId,
-  userId: scope.claims.userId,
-});
-
-const toView = (item: AssetItem, streamBase: string): MediaItemView => ({
-  id: item.id,
-  kind: item.kind,
-  title: item.title,
-  // Progressive is ALWAYS present; HLS is the optional upgrade (04 V2's pinned
-  // AV semantics — `hls:false` degrades to `streamUrl`, it does not 404). The
-  // stream/hls URLs are uniform across sources: `read` resolves the id against
-  // whichever source owns it, so the transport path never needs to know the
-  // origin.
-  streamUrl: `${streamBase}/${item.id}/bytes`,
-  hlsUrl: item.hasHls ? `${streamBase}/${item.id}/hls` : undefined,
-  private: item.private,
-});
-
-/** How many items a `list` page holds when it unions the registered sources. */
-const PAGE_LIMIT = 50;
-
-/**
- * The union cursor: a source index plus that source's own opaque continuation.
- * The service drains sources IN ORDER (catalogue, then each extra) — a
- * concatenation pager. It is complete (every item appears) and duplicate-free
- * (each source is fully drained before the next), which a naive merge without a
- * shared sort key could not guarantee. Cross-source chronological interleaving is
- * a client concern that rides 02's generated app (04 §5); the contract this tier
- * owes is completeness and stability, and this delivers both.
- */
-interface UnionCursor {
-  i: number;
-  inner?: string;
-}
-
-const encodeUnionCursor = (c: UnionCursor): string =>
-  Buffer.from(JSON.stringify(c)).toString('base64url');
-
-const decodeUnionCursor = (cursor: string | undefined): UnionCursor => {
-  if (!cursor) return { i: 0 };
-  try {
-    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as { i?: unknown; inner?: unknown };
-    const i = typeof parsed.i === 'number' && parsed.i >= 0 ? Math.floor(parsed.i) : 0;
-    const inner = typeof parsed.inner === 'string' ? parsed.inner : undefined;
-    return { i, inner };
-  } catch {
-    return { i: 0 };
-  }
-};
-
-let uploadSequence = 0;
-const defaultMintId = (): string => {
-  uploadSequence += 1;
-  return `file_${Date.now().toString(36)}_${uploadSequence.toString(36)}`;
-};
-
-export function createAssetService(options: AssetServiceOptions): AssetService {
-  // The BOOT gate for the binary tier (08 §1 "Gates" → `object-store-missing`).
-  // The type says `objects` is required, but a host wiring services from parsed
-  // config can still hand over `undefined`; without this the first upload dies
-  // with `Cannot read properties of undefined` deep inside the service. 04's law
-  // is that a missing implementation for an effective feature is a BOOT failure,
-  // never a first-request 500 — services are constructed at boot, so this is
-  // that moment.
-  if (!options.objects)
-    throw new AppError(
-      'The asset engine is active but no ObjectStore was provided. Wire `createFsObjectStore` (local) or `createS3ObjectStore` (saas) — refusing to boot an asset engine that cannot store a byte.',
-      { code: 'OBJECT_STORE_MISSING', status: 500, category: 'storage', isOperational: false },
-    );
-  if (!options.telemetry)
-    throw new AppError(
-      'The asset engine is active but no TelemetryWriter was provided; uploads would store bytes that are never metered (08 §5).',
-      { code: 'STORAGE_METER_MISSING', status: 500, category: 'storage', isOperational: false },
-    );
-
-  const domain = () => options.storage.domain('media');
-  const mint = options.mintId ?? defaultMintId;
-  const streamBase = '/api/asset/items';
-  // The catalogue is always present and first; extra origins (the vault) follow.
-  // Every read path unions over THIS list rather than naming a table (§2b).
-  const sources: readonly AssetSource[] = [createCatalogueMediaSource(options.storage), ...(options.sources ?? [])];
-
-  return {
-    async list(scope, opts): Promise<Page<MediaItemView>> {
-      // `revealPrivate` comes from the route's decision about the VERIFIED
-      // session, never from the request body — each source applies it in SQL.
-      const repoScope = scopeOf(scope);
-      const start = decodeUnionCursor(opts.cursor);
-      const items: MediaItemView[] = [];
-      let i = start.i;
-      let inner = start.inner;
-      while (i < sources.length && items.length < PAGE_LIMIT) {
-        const remaining = PAGE_LIMIT - items.length;
-        const page = await sources[i]!.list(repoScope, { revealPrivate: opts.revealPrivate, limit: remaining, cursor: inner });
-        for (const item of page.items) items.push(toView(item, streamBase));
-        if (page.cursor) {
-          // This source has more — stop here with a cursor pointing into it.
-          return { items, cursor: encodeUnionCursor({ i, inner: page.cursor }) };
-        }
-        // Source drained; advance to the next with a fresh (empty) inner cursor.
-        i += 1;
-        inner = undefined;
-      }
-      // Either the page filled (more sources may remain) or every source drained.
-      return { items, cursor: i < sources.length ? encodeUnionCursor({ i }) : undefined };
-    },
-
-    async get(scope, id): Promise<MediaItemView | null> {
-      // The detail read unions in the SAME order as `list`/`read`: the first
-      // source that owns the id answers, and a source that does not own it says
-      // so with a null rather than throwing. Private items are absent by
-      // construction on every source (see `AssetSource.get`).
-      const repoScope = scopeOf(scope);
-      for (const source of sources) {
-        const item = await source.get(repoScope, id);
-        if (item) return toView(item, streamBase);
-      }
-      return null;
-    },
-
-    async read(scope, id): Promise<ReadableStream<Uint8Array> | null> {
-      // Fail-closed on a private id BY CONSTRUCTION: `resolvePublic` cannot return
-      // one, on any source (§4.3). The first source that owns the id wins; the
-      // mixin turns a null (no source owns it) into a typed 404, which also keeps
-      // the id's existence undisclosed.
-      const repoScope = scopeOf(scope);
-      for (const source of sources) {
-        const ref = await source.resolvePublic(repoScope, id);
-        if (ref) return await options.objects.get(ref.objectKey);
-      }
-      return null;
-    },
-
-    async readPrivate(scope, id): Promise<ReadableStream<Uint8Array> | null> {
-      const repoScope = scopeOf(scope);
-      for (const source of sources) {
-        const ref = await source.resolvePrivate(repoScope, id);
-        if (!ref) continue;
-        if (!options.openPrivateBytes)
-          throw new AppError(
-            'This host serves private media but wired no decryptor. Provide `openPrivateBytes` (GuardEngine owns the key) — refusing to stream ciphertext.',
-            { code: 'PRIVATE_MEDIA_DECRYPTOR_MISSING', status: 500, category: 'security', isOperational: false },
-          );
-        // The scheme is read off the ROW, so a file sealed under an older
-        // envelope opens with that envelope rather than today's default.
-        return await options.openPrivateBytes(ref.objectKey, ref.encryption ?? 'aes-256-gcm');
-      }
-      return null;
-    },
-
-    async hlsPlaylist(scope, id): Promise<string | null> {
-      const repoScope = scopeOf(scope);
-      const rendition = await scopedExec(domain(), repoScope, readHlsRendition(repoScope, id));
-      if (!rendition) return null;
-      const body = await options.objects.get(rendition.objectKey);
-      if (!body) return null;
-      return await new Response(body).text();
-    },
-
-    async upload(scope, request): Promise<{ id: string }> {
-      const body = request.body;
-      if (!body)
-        throw new AppError('Upload request carried no body stream.', { code: 'UPLOAD_BODY_MISSING', status: 400 });
-
-      const id = mint();
-      const contentType = request.headers.get('content-type') ?? 'application/octet-stream';
-      const displayName = request.headers.get('x-cc-filename') ?? id;
-      const objectKey = `${scope.claims.tenantId}/${id}`;
-
-      // Straight from the request stream to the store — whole-file RAM
-      // buffering is banned (01 §2.5), so this works for a 4GB video.
-      const stat = await options.objects.put(objectKey, body, { contentType });
-
-      // Meter the moment the bytes are durable and BEFORE the catalogue row
-      // (08 §5). The order is deliberate: from here on the tenant is consuming
-      // storage whether or not the catalogue write succeeds, so metering after
-      // it would under-bill exactly the failure case. `recordMeterEvent` is
-      // synchronous-durable — it returns only once the row is committed or
-      // fsync'd to the spill journal — so this is the never-drop path, not a
-      // best-effort emit.
-      //
-      // The event uuid is derived from the object key, so a retried upload of
-      // the SAME object is idempotent rather than double-billed.
-      options.telemetry.recordMeterEvent({
-        eventUuid: `storage.put:${objectKey}`,
-        tenantId: scope.claims.tenantId,
-        metric: STORAGE_METRIC,
-        qty: stat.size,
-        meta: { fileId: id, objectKey, contentType },
-      });
-
-      const repoScope = scopeOf(scope);
-      await scopedExec(
-        domain(),
-        repoScope,
-        catalogueMediaFile(repoScope, {
-          id,
-          objectKey,
-          relPath: displayName,
-          displayName,
-          mimeType: contentType,
-          byteSize: stat.size,
-        }),
-      );
-      return { id };
-    },
-
-    async remove(scope, id): Promise<boolean> {
-      const repoScope = scopeOf(scope);
-      // The first source that owns the id soft-deletes it and reports freed
-      // bytes; a catalogue file goes through `deleteMediaFile`, a vault asset
-      // through `trashAsset`. Unknown/foreign/already-trashed on EVERY source ⇒
-      // nothing freed, no credit; the mixin turns `false` into a typed 404.
-      for (const source of sources) {
-        const freed = await source.remove(repoScope, id);
-        if (!freed) continue;
-        // Post the NEGATIVE storage credit so the meter reconciles to net bytes
-        // (§2c) instead of staying a monotonic gross counter. The event uuid
-        // mirrors the upload's `storage.put:<key>` slot, so a retried delete is
-        // idempotent — and each source only reports a file the FIRST time it is
-        // trashed, so the credit is posted at most once regardless. Durable by
-        // the same never-drop path the upload meter uses.
-        options.telemetry.recordMeterEvent({
-          eventUuid: `storage.delete:${freed.objectKey}`,
-          tenantId: scope.claims.tenantId,
-          metric: STORAGE_METRIC,
-          qty: -freed.byteSize,
-          meta: { fileId: id, objectKey: freed.objectKey },
-        });
-        return true;
-      }
-      return false;
-    },
-
-    async requestOcr(scope, id): Promise<{ jobId: string }> {
-      const repoScope = scopeOf(scope);
-      const file = await scopedExec(domain(), repoScope, readPublicMediaFile(repoScope, id));
-      if (!file)
-        throw new AppError(`No media item '${id}'.`, {
-          code: 'MEDIA_NOT_FOUND',
-          status: 404,
-          context: { id },
-        });
-      const jobId = await options.broker.enqueue({
-        kind: ASSET_OCR_JOB,
-        tenantId: scope.claims.tenantId,
-        instanceId: scope.instanceId,
-        // userId travels so the OCR-created knowledge note is owned by the real
-        // caller, not the handler's `system` fallback.
-        payload: { fileId: id, objectKey: file.objectKey, userId: repoScope.userId },
-      });
-      return { jobId };
-    },
-
-    async vaultUpload(scope, request): Promise<VaultUploadResultView> {
-      const body = request.body;
-      if (!body)
-        throw new AppError('Vault upload carried no body stream.', { code: 'UPLOAD_BODY_MISSING', status: 400 });
-
-      const repoScope = scopeOf(scope);
-      const contentType = request.headers.get('content-type') ?? 'application/octet-stream';
-      const fileName = decodeUploadFileName(request.headers.get('x-cc-filename'));
-      // The declared length is only the staging estimate — it may be absent under
-      // chunked transfer, and a lying/truncated client would make it wrong. The
-      // authoritative size is what we actually stream (counted below).
-      const declaredSize = Number(request.headers.get('content-length')) || 0;
-
-      // 1. Open the staging row BEFORE a byte moves, so a crash mid-stream leaves a
-      //    visible `processing` upload rather than an untracked write.
-      const upload = await scopedExec(
-        domain(),
-        repoScope,
-        vaultRepo.beginUpload(repoScope, { fileName, mimeType: contentType, byteSize: declaredSize }),
-      );
-
-      // 2. Stream straight to a per-upload object key while a SHA-256 is computed
-      //    over the chunks AS THEY FLOW — no whole-file RAM buffer (01 §2.5). The
-      //    key is per-upload, not content-addressed: we cannot know the hash until
-      //    the last byte, and the ObjectStore has no move. Content addressing is
-      //    enforced at the ROW (`UNIQUE (tenant_id, checksum)`); a redundant object
-      //    from a dedupe is reclaimed in step 4.
-      const uploadKey = `${repoScope.tenantId}/vault/${upload.id}`;
-      const hashing = hashingPassThrough(body);
-      try {
-        await options.objects.put(uploadKey, hashing.stream, { contentType });
-      } catch (err) {
-        // The bytes never settled — mark the staging row `failed` so it is not left
-        // masquerading as `processing`, then surface the store error.
-        await scopedExec(domain(), repoScope, vaultRepo.failUpload(repoScope, upload.id)).catch(() => {});
-        throw err;
-      }
-      const checksum = hashing.digest();
-      const size = hashing.byteCount();
-
-      // Everything from here on runs under the SAME compensation as the `put`
-      // above (05 §A2). It did not, and that was the leak: a DB error AFTER the
-      // object settled left the `mv_uploads` row `processing` FOREVER — no
-      // `failUpload`, no object delete — so the poll route reported an upload
-      // still in flight, the object was unreferenced by any asset, and the
-      // storage it occupied was invisible to the meter. Only the `put` was
-      // guarded, which is exactly the half that already cleans up after itself.
-      let result: Awaited<ReturnType<typeof vaultRepo.completeUpload>>;
-      try {
-        // Record the true received count so the poll route reads reality, not the
-        // (possibly absent/wrong) declared length.
-        await scopedExec(domain(), repoScope, vaultRepo.recordUploadProgress(repoScope, upload.id, size));
-
-        // 3. Promote to an `mv_assets` row ATOMICALLY. `completeUpload` dedupes on the
-        //    checksum, and takes the ACTUAL streamed size so the asset, the meter, and
-        //    the eventual delete credit all agree on one number.
-        result = await vaultRepo.completeUpload(domain(), repoScope, upload.id, {
-          checksum,
-          objectKey: uploadKey,
-          mimeType: contentType,
-          title: fileName,
-          byteSize: size,
-        });
-      } catch (err) {
-        // The same compensation the `put` catch does, in the same order the
-        // reaper uses: drop the object we streamed, THEN mark the row. Both are
-        // best-effort — the original failure is what the caller needs to see,
-        // and a stranded row is now bounded by the reaper rather than forever.
-        await options.objects.delete(uploadKey).catch(() => {});
-        await scopedExec(domain(), repoScope, vaultRepo.failUpload(repoScope, upload.id)).catch(() => {});
-        throw err;
-      }
-
-      // 4. Meter only NEW bytes. On a dedupe the canonical asset points at an
-      //    earlier object, so the one we just streamed is redundant: reclaim it and
-      //    post no meter event — a dedupe consumes zero new storage. On a fresh
-      //    asset, meter the actual bytes on the never-drop path with an
-      //    object-key-derived uuid (idempotent on retry), mirroring `upload`.
-      if (result.deduped) {
-        // A failed reclaim is storage-meter DRIFT (law #6): the tenant is billed
-        // for nothing, and a silent `.catch(() => {})` is how that stays
-        // undiscovered. Report it and let the host's sink decide.
-        await options.objects.delete(uploadKey).catch((err: unknown) => {
-          options.onOrphanedObject?.({ objectKey: uploadKey, tenantId: repoScope.tenantId, cause: err });
-        });
-      } else {
-        options.telemetry.recordMeterEvent({
-          eventUuid: `storage.put:${uploadKey}`,
-          tenantId: repoScope.tenantId,
-          metric: STORAGE_METRIC,
-          qty: size,
-          meta: { assetId: result.asset.id, objectKey: uploadKey, contentType },
-        });
-      }
-
-      return { uploadId: upload.id, asset: toVaultAssetView(result.asset), deduped: result.deduped };
-    },
-
-    async vaultUploadStatus(scope, id): Promise<VaultUploadStatusView | null> {
-      const upload = await scopedExec(domain(), scopeOf(scope), vaultRepo.getUpload(scopeOf(scope), id));
-      return upload ? toVaultUploadStatusView(upload) : null;
-    },
-
-    async reapStaleUploads(scope, reapOptions = {}): Promise<{ reaped: number; objectsDeleted: number }> {
-      const repoScope = scopeOf(scope);
-      const olderThan = new Date(Date.now() - (reapOptions.olderThanMs ?? VAULT_UPLOAD_STALE_MS)).toISOString();
-      const stale = await scopedExec(
-        domain(),
-        repoScope,
-        vaultRepo.listStaleUploads(repoScope, olderThan, reapOptions.limit ?? 100),
-      );
-
-      let reaped = 0;
-      let objectsDeleted = 0;
-      for (const upload of stale) {
-        // The object key is DERIVED, exactly as `vaultUpload` derives it — the
-        // staging row does not store one, because the key is only meaningful
-        // while the upload is in flight. Deleting a key that was never written
-        // is a no-op in both stores, which is why this is safe for a row that
-        // died before its first byte.
-        const objectKey = `${repoScope.tenantId}/vault/${upload.id}`;
-        try {
-          await options.objects.delete(objectKey);
-          objectsDeleted += 1;
-        } catch (err) {
-          // Report and keep going. A store that cannot delete one object must
-          // not stop the row from being marked — a `processing` row is what the
-          // poll route lies about, and leaving it is the worse of the two.
-          options.onOrphanedObject?.({ objectKey, tenantId: repoScope.tenantId, cause: err });
-        }
-        // `failUpload` is a no-op on anything already terminal, so a row that
-        // completed between the list and here is not clobbered.
-        if (await scopedExec(domain(), repoScope, vaultRepo.failUpload(repoScope, upload.id))) reaped += 1;
-      }
-      return { reaped, objectsDeleted };
-    },
-
-    // Vault albums (§2a / §4) live in `media.db` beside the file catalogue, so
-    // the SAME domain accessor serves them. A thin `scopedExec` over `vaultRepo`.
-    albums: createAlbumService(domain),
-    sources: createSourceService(domain),
-
-    // Present only when the host wired a local verifier; the mixin keys the
-    // route's existence off that (see `AssetService.readSignedObject`).
-    ...(options.verifySignedUrl
-      ? {
-          async readSignedObject(claim): Promise<{ body: ReadableStream<Uint8Array>; contentType?: string } | null> {
-            // Verify FIRST. The signature is the whole authorization for this
-            // route — there is no session on it, by design, because the URL is
-            // handed to an <img>/<video> tag that cannot carry one.
-            if (!options.verifySignedUrl?.(claim)) return null;
-            const body = await options.objects.get(claim.key);
-            if (!body) return null;
-            const stat = await options.objects.stat(claim.key);
-            return { body, contentType: stat?.contentType };
-          },
-        }
-      : {}),
-  };
-}
-
-/**
- * The upload's declared file name, read off `x-cc-filename` (03 §1c).
- *
- * A header value is ISO-8859-1 on the wire, so a browser `fetch` REFUSES to send
- * `café.png` — the request throws before a byte leaves. The client therefore
- * percent-encodes the name and this decodes it, which is why the two halves must
- * be read together.
- *
- * A value that is not valid percent-encoding (`100%.png` from a hand-rolled
- * caller, or any pre-03 client that never encoded) is taken AS IS rather than
- * refused: the name is a LABEL on the asset, and rejecting an upload over its
- * label — after the bytes already streamed — would be the tail wagging the dog.
- * Plain ASCII decodes to itself, so every existing caller is unaffected.
- */
-export const decodeUploadFileName = (raw: string | null): string => {
-  if (!raw) return 'upload';
-  try {
-    return decodeURIComponent(raw) || 'upload';
-  } catch {
-    return raw;
-  }
-};
-
-const toVaultAssetView = (asset: vaultRepo.VaultAsset): VaultAssetView => ({
-  id: asset.id,
-  title: asset.title || undefined,
-  mimeType: asset.mimeType,
-  byteSize: asset.byteSize,
-  checksum: asset.checksum,
-  createdAt: asset.createdAt,
-});
-
-const toVaultUploadStatusView = (upload: vaultRepo.VaultUpload): VaultUploadStatusView => ({
-  id: upload.id,
-  fileName: upload.fileName,
-  mimeType: upload.mimeType,
-  byteSize: upload.byteSize,
-  received: upload.received,
-  status: upload.status,
-  checksum: upload.checksum,
-  completedAt: upload.completedAt,
-});
-
-/**
- * A pass-through over an upload's byte stream that computes a SHA-256 and counts
- * bytes AS THEY FLOW, never buffering the whole file (01 §2.5 — a 4GB video is a
- * pipe, not a buffer). The `TransformStream` hashes each chunk and re-enqueues it
- * unchanged, so the ObjectStore consumes the same bytes; `digest()`/`byteCount()`
- * are valid once the store has drained the stream (its `put` awaits completion).
- * The digest is the content address the vault keys on — a real cryptographic hash,
- * NOT `stableHash` (an 8-hex FNV over JSON, unfit for large-binary integrity).
- */
-interface HashingStream {
-  stream: ReadableStream<Uint8Array>;
-  digest: () => string;
-  byteCount: () => number;
-}
-
-const hashingPassThrough = (source: ReadableStream<Uint8Array>): HashingStream => {
-  const hash = createHash('sha256');
-  let bytes = 0;
-  const transform = new TransformStream<Uint8Array, Uint8Array>({
-    transform(chunk, controller) {
-      hash.update(chunk);
-      bytes += chunk.byteLength;
-      controller.enqueue(chunk);
-    },
-  });
-  return { stream: source.pipeThrough(transform), digest: () => hash.digest('hex'), byteCount: () => bytes };
-};
-
-const toAlbumView = (album: vaultRepo.VaultAlbum): AlbumView => ({
-  id: album.id,
-  title: album.title,
-  coverId: album.coverId,
-  createdAt: album.createdAt,
-});
-const toAlbumAssetView = (asset: vaultRepo.VaultAsset): AlbumAssetView => ({
-  id: asset.id,
-  title: asset.title,
-  mimeType: asset.mimeType,
-  byteSize: asset.byteSize,
-});
-
-/**
- * The vault-album sub-service (§2a / §4). It closes over the SAME `media`
- * domain accessor the file catalogue uses, so an album and an asset share one
- * database. Membership mutations return `false` for a foreign album/asset — the
- * repo guards both sides in SQL and the mixin turns that into a typed 404.
- * Ordered membership reorder is ONE `UPDATE … SET position` in the repo.
- */
-function createAlbumService(domain: () => DomainHandle): AlbumService {
-  const run = <T>(scope: CallScope, op: RepoOp<T>): Promise<T> => scopedExec(domain(), scopeOf(scope), op);
-  return {
-    async list(scope): Promise<readonly AlbumView[]> {
-      return (await run(scope, vaultRepo.listAlbums(scopeOf(scope)))).map(toAlbumView);
-    },
-    async get(scope, id): Promise<AlbumView | null> {
-      const album = await run(scope, vaultRepo.getAlbum(scopeOf(scope), id));
-      return album ? toAlbumView(album) : null;
-    },
-    async create(scope, input): Promise<AlbumView> {
-      return toAlbumView(await run(scope, vaultRepo.createAlbum(scopeOf(scope), input)));
-    },
-    async update(scope, id, patch): Promise<AlbumView | null> {
-      const album = await run(scope, vaultRepo.updateAlbum(scopeOf(scope), id, patch));
-      return album ? toAlbumView(album) : null;
-    },
-    async remove(scope, id): Promise<boolean> {
-      return await run(scope, vaultRepo.deleteAlbum(scopeOf(scope), id));
-    },
-    async listAssets(scope, albumId): Promise<readonly AlbumAssetView[]> {
-      return (await run(scope, vaultRepo.listAlbumAssets(scopeOf(scope), albumId))).map(toAlbumAssetView);
-    },
-    async addAsset(scope, albumId, assetId, position): Promise<boolean> {
-      return await run(scope, vaultRepo.addToAlbum(scopeOf(scope), albumId, assetId, position));
-    },
-    async reorderAsset(scope, albumId, assetId, position): Promise<boolean> {
-      return await run(scope, vaultRepo.reorderAlbumMember(scopeOf(scope), albumId, assetId, position));
-    },
-    async removeAsset(scope, albumId, assetId): Promise<boolean> {
-      return await run(scope, vaultRepo.removeFromAlbum(scopeOf(scope), albumId, assetId));
-    },
-  };
-}
-
-/**
- * Vault SOURCE CRUD (`mv_sources`) — the rows that replaced `mediaSources: [...]`.
- *
- * These repository ops have existed since the vault landed and had NO consumer:
- * a customer could not see, name, or retire a source through any surface, so the
- * table that exists precisely to keep source configuration out of a config file
- * could only be populated by a migration or by hand. Law #1's amended first arm
- * (E8) is what this closes — orphaned-because-unfinished, so finish it.
- *
- * **`kind` is validated HERE, not at the route.** A `mv_sources.kind` outside
- * `MEDIA_SOURCE_KINDS` is a row every reader would then have to branch on
- * defensively, and SQLite will not refuse it for us. Validating in the service
- * means the rule holds for a future op handler or job that never goes through an
- * HTTP route.
- */
-function createSourceService(domain: () => DomainHandle): SourceService {
-  const run = <T>(scope: CallScope, op: RepoOp<T>): Promise<T> => scopedExec(domain(), scopeOf(scope), op);
-  return {
-    async list(scope): Promise<readonly SourceView[]> {
-      return (await run(scope, vaultRepo.listSources(scopeOf(scope)))).map(toSourceView);
-    },
-    async get(scope, id): Promise<SourceView | null> {
-      const source = await run(scope, vaultRepo.getSource(scopeOf(scope), id));
-      return source ? toSourceView(source) : null;
-    },
-    async create(scope, input): Promise<SourceView> {
-      const kind = assertSourceKind(input.kind);
-      return toSourceView(
-        await run(
-          scope,
-          vaultRepo.createSource(scopeOf(scope), {
-            kind,
-            title: input.title,
-            rootKey: input.rootKey,
-            readOnly: input.readOnly,
-          }),
-        ),
-      );
-    },
-    async update(scope, id, patch): Promise<SourceView | null> {
-      const source = await run(scope, vaultRepo.updateSource(scopeOf(scope), id, patch));
-      return source ? toSourceView(source) : null;
-    },
-    async remove(scope, id): Promise<boolean> {
-      return await run(scope, vaultRepo.deleteSource(scopeOf(scope), id));
-    },
-  };
-}
-
-const toSourceView = (source: vaultRepo.VaultSource): SourceView => ({
-  id: source.id,
-  kind: source.kind,
-  title: source.title,
-  rootKey: source.rootKey,
-  readOnly: source.readOnly,
-});
-
-/** A typed 400 rather than a row every downstream reader has to defend against. */
-const assertSourceKind = (kind: string): MediaSourceKind => {
-  if ((MEDIA_SOURCE_KINDS as readonly string[]).includes(kind)) return kind as MediaSourceKind;
-  throw new AppError(`'${kind}' is not a media source kind.`, {
-    code: 'SOURCE_KIND_UNKNOWN',
-    status: 400,
-    context: { kind, allowed: [...MEDIA_SOURCE_KINDS] },
-  });
-};