@ultimat3/cli 26.1.1 → 27.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "26.1.1",
+  "version": "27.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "26.1.1",
-    "@ultimat3/admin": "26.1.1",
-    "@ultimat3/ai": "26.1.1",
-    "@ultimat3/auth": "26.1.1",
-    "@ultimat3/cache": "26.1.1",
-    "@ultimat3/core": "26.1.1",
-    "@ultimat3/db": "26.1.1",
-    "@ultimat3/entity": "26.1.1",
-    "@ultimat3/flags": "26.1.1",
-    "@ultimat3/http": "26.1.1",
-    "@ultimat3/i18n": "26.1.1",
-    "@ultimat3/jobs": "26.1.1",
-    "@ultimat3/mail": "26.1.1",
-    "@ultimat3/manifest": "26.1.1",
-    "@ultimat3/mcp": "26.1.1",
-    "@ultimat3/money": "26.1.1",
-    "@ultimat3/notify": "26.1.1",
-    "@ultimat3/policy": "26.1.1",
-    "@ultimat3/pwa": "26.1.1",
-    "@ultimat3/query": "26.1.1",
-    "@ultimat3/realtime": "26.1.1",
-    "@ultimat3/render": "26.1.1",
-    "@ultimat3/schema": "26.1.1",
-    "@ultimat3/seo": "26.1.1",
-    "@ultimat3/storage": "26.1.1",
-    "@ultimat3/testing": "26.1.1",
-    "@ultimat3/time": "26.1.1",
+    "@ultimat3/action": "27.1.0",
+    "@ultimat3/admin": "27.1.0",
+    "@ultimat3/ai": "27.1.0",
+    "@ultimat3/auth": "27.1.0",
+    "@ultimat3/cache": "27.1.0",
+    "@ultimat3/core": "27.1.0",
+    "@ultimat3/db": "27.1.0",
+    "@ultimat3/entity": "27.1.0",
+    "@ultimat3/flags": "27.1.0",
+    "@ultimat3/http": "27.1.0",
+    "@ultimat3/i18n": "27.1.0",
+    "@ultimat3/jobs": "27.1.0",
+    "@ultimat3/mail": "27.1.0",
+    "@ultimat3/manifest": "27.1.0",
+    "@ultimat3/mcp": "27.1.0",
+    "@ultimat3/money": "27.1.0",
+    "@ultimat3/notify": "27.1.0",
+    "@ultimat3/policy": "27.1.0",
+    "@ultimat3/pwa": "27.1.0",
+    "@ultimat3/query": "27.1.0",
+    "@ultimat3/realtime": "27.1.0",
+    "@ultimat3/render": "27.1.0",
+    "@ultimat3/schema": "27.1.0",
+    "@ultimat3/seo": "27.1.0",
+    "@ultimat3/storage": "27.1.0",
+    "@ultimat3/testing": "27.1.0",
+    "@ultimat3/time": "27.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -419,8 +419,13 @@ function reloadRoute(
 
 const countSuspense = (source: string): number => source.match(/<Suspense[\s/>]/g)?.length ?? 0;
 
-/** `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web`. */
-const workspaceOf = (file: string): string => file.split('/').slice(0, 2).join('/');
+/**
+ * `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web` — on
+ * either separator. A manifest written on Windows split a `\`-path on `/`, kept the whole file as
+ * the "package" (`apps\\admin\\app\\…\\abuse.tsx`) and sorted the codes by it, so the same tree
+ * regenerated thousands of changed lines on the next Linux machine and `--check` meant nothing.
+ */
+export const workspaceOf = (file: string): string => toPosix(file).split('/').slice(0, 2).join('/');
 
 /**
  * The app's `X_*` codes, from the same walk and the same scanner the `errors` gate step uses.

package/src/app-permissions.ts

@@ -16,7 +16,6 @@ import {
   roleDefinitions,
 } from '@ultimat3/policy';
 import { routeEntries } from '@ultimat3/render';
-import { definedStorage } from '@ultimat3/storage';
 import { loadApp } from './app-load';
 import { borrowedFinding, borrowedPermissions, permissionsFile } from './app-permissions-borrowed';
 import { siteFile } from './app-permissions-site';
@@ -25,7 +24,6 @@ import { duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { ungrantedFinding, ungrantedRequirements } from './permission-grants';
-import { STORAGE_READ_PERMISSION } from './runtime-storage';
 
 /** One place a permission is named by a string the framework never checks. */
 export interface PermissionReference {
@@ -37,8 +35,6 @@ export interface PermissionReference {
   readonly grant?: true;
   /** App-root-relative POSIX path of the declaration, or `undefined` when it is not derivable. */
   readonly at: string | undefined;
-  /** Who requires it when no app file does — a route the framework mounts. */
-  readonly requiredBy?: string;
 }
 
 /** What this check needs of a boot — the seam `i18n-registration.ts` already established. */
@@ -76,31 +72,10 @@ export function roleMapFile(root: string): string | undefined {
  * and the running server cannot be looking at two different sets.
  */
 export function requiredReferences(): readonly PermissionReference[] {
-  const routes = routeEntries().flatMap((entry) => {
+  return routeEntries().flatMap((entry) => {
     const permission = entry.config.policy?.permission;
     return permission === undefined ? [] : [{ permission, at: entry.file }];
   });
-  return [...routes, ...storageReferences()];
-}
-
-/**
- * The framework's own `GET /_storage/:disk/*key` and `/media/*key` require `storage:read`
- * (`runtime-storage.ts`), and an app whose permission set lacks it got `500 X_PERMISSION_UNKNOWN`
- * on the first signed URL it minted — at runtime, from a route it never wrote (#524). Asked only
- * of an app that declared its own disks (`defineStorage` in an app module, which is what those
- * routes then serve): one that stores nothing mints no URL, and requiring a permission it has no
- * use for would be a finding with no reader.
- */
-function storageReferences(): readonly PermissionReference[] {
-  return definedStorage() === undefined
-    ? []
-    : [
-        {
-          permission: STORAGE_READ_PERMISSION,
-          at: undefined,
-          requiredBy: 'the mounted GET /_storage/:disk/*key and /media/*key routes',
-        },
-      ];
 }
 
 /**
@@ -147,11 +122,7 @@ export function permissionFindings(root: string): readonly Finding[] {
   );
   const known = knownPermissions();
   return references.map((reference) => {
-    const base = findingFrom(permissionUnknown(reference.permission, known));
-    const finding =
-      reference.requiredBy === undefined
-        ? base
-        : { ...base, cause: `${base.cause} — required by ${reference.requiredBy}` };
+    const finding = findingFrom(permissionUnknown(reference.permission, known));
     return reference.at === undefined ? finding : { ...finding, at: reference.at };
   });
 }

package/src/app-reload-graph.ts

@@ -24,7 +24,7 @@
 import { resolve } from 'node:path';
 import { registeredStylesheets } from '@ultimat3/render/server';
 import { resolvedImports } from './module-imports';
-import { hasPathSegment } from './path-segments';
+import { hasPathSegment, isPathUnder } from './path-segments';
 
 type Kind = 'script' | 'style' | 'data';
 
@@ -106,7 +106,7 @@ const hashOf = (text: string | null): bigint | null =>
 /** The in-app files `source` imports — a package under `node_modules` is not the app's to reload. */
 const importsOf = (path: string, source: string, root: string): string[] =>
   resolvedImports(path, source, 'referenced').filter(
-    (target) => target.startsWith(`${root}/`) && !hasPathSegment(target, 'node_modules'),
+    (target) => isPathUnder(root, target) && !hasPathSegment(target, 'node_modules'),
   );
 
 function link(from: string, to: string): void {
@@ -156,7 +156,7 @@ export async function trackStylesheets(root: string): Promise<void> {
   if (!tracking) return;
   const base = resolve(root);
   const inApp = (path: string): boolean =>
-    path.startsWith(`${base}/`) && !hasPathSegment(path, 'node_modules');
+    isPathUnder(base, path) && !hasPathSegment(path, 'node_modules');
   for (const sheet of registeredStylesheets()) {
     if (!inApp(sheet.file)) continue;
     if (!nodes.has(sheet.file)) await track(sheet.file, await readText(sheet.file), base);

package/src/budgets.ts

@@ -86,7 +86,9 @@ const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.bu
 export type RouteFileOf = (url: string) => string | undefined;
 
 const declaredFileOf: RouteFileOf = (url) =>
-  describePages().find((route) => route.path === url && route.mount === undefined)?.file;
+  describePages().find(
+    (route) => route.path === url && (route.mount === undefined || route.mount.claimed === true),
+  )?.file;
 
 const KB = 1024;
 

package/src/cmd-generate.ts

@@ -323,7 +323,14 @@ async function readSliceErrors(
 }
 
 /** The generators whose output depends on what the slice's `entity.ts` / `repo.ts` declare. */
-const READS_SLICE: ReadonlySet<Generator> = new Set(['job', 'task', 'action', 'mutator', 'query']);
+const READS_SLICE: ReadonlySet<Generator> = new Set([
+  'job',
+  'task',
+  'action',
+  'mutator',
+  'query',
+  'backfill',
+]);
 
 /**
  * The slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the generator's kind reads

package/src/dev-watch-tree.ts

@@ -16,7 +16,7 @@ import { join } from 'node:path';
 import { finiteCount, logger } from '@ultimat3/core';
 import type { DevIgnore } from './dev-watch';
 import { devIgnore } from './dev-watch';
-import { pathSegments } from './path-segments';
+import { isPathUnder, pathSegments } from './path-segments';
 
 /** What `node:fs`'s watcher hands a listener — `filename` is optional in fact, not only in type. */
 export type WatchListener = (event: string, filename: string | Buffer | null | undefined) => void;
@@ -213,7 +213,9 @@ class WatchDirectoryMap {
 
   remove(directory: string): void {
     for (const held of this.#watchers.keys()) {
-      if (held !== directory && !held.startsWith(`${directory}/`)) continue;
+      // Either separator: on Windows a held directory is `C:\app\apps\web`, and a `/` test
+      // closed none of the watchers below a removed directory.
+      if (held !== directory && !isPathUnder(directory, held)) continue;
       this.#watchers.get(held)?.close();
       this.#watchers.delete(held);
     }

package/src/error-codes.ts

@@ -231,6 +231,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_DEV_STATE_UNWRITABLE',
   'X_PACKAGE_TEST_ONLY_SHIPPED',
   'X_ISLAND_MODULE_DUPLICATED',
+  'X_BACKFILL_SLICE_ENTITY',
 ] as const;
 
 /**
@@ -418,6 +419,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DEV_STATE_UNWRITABLE: 'x dev cannot claim its state directory',
   X_PACKAGE_TEST_ONLY_SHIPPED: 'a test-only module ships in the tarball',
   X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
+  X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/generate-files.ts

@@ -61,7 +61,7 @@ export interface GenerateOptions {
    */
   readonly sliceErrors?: string;
   /**
-   * `action`, `mutator`, `query`, `job` and `task`: the slice's `entity.ts` as it stands on disk, absent when
+   * `action`, `mutator`, `query`, `job`, `task` and `backfill`: the slice's `entity.ts` as it stands on disk, absent when
    * the feature has no entity yet — and then none is written. Supplied by `run` for `sliceErrors`'s reason — whether the feature is
    * tenant-scoped is a fact about THIS app, and a template that assumed `tenant: 'orgId'` wrote
    * `repo.byId`/`repo.list` calls into a feature whose entity names no tenant column. Read at
@@ -166,6 +166,8 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         backfillFiles(options.name, {
           ...target,
           ...(options.locales === undefined ? {} : { locales: options.locales }),
+          ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
+          ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),
       );
     case 'entity':

package/src/index.ts

@@ -137,6 +137,10 @@ export { startQueue } from './runtime-queue';
 export { appRoutes, routeDocument } from './runtime-render';
 export type { RunningServices } from './runtime-services';
 export { startServices } from './runtime-services';
+// The `/_storage` pair `x dev` and `runRole` mount, for an app's contract test of the real route
+// over HTTP — the way `assetRoutes` already serves `/media` to one.
+export type { StorageRoutesOptions } from './runtime-storage';
+export { STORAGE_READ_PERMISSION, servedStorage, storageRoutes } from './runtime-storage';
 // The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
 export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
 export { checkSchemaDump } from './schema-dump-drift';

package/src/mcp-errors.ts

@@ -300,6 +300,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'bun run x -- verify --only package-shape --json   # then rename each listed module to <name>-fixture.ts and update its importers',
   X_ISLAND_MODULE_DUPLICATED:
     'gh issue create --repo developerz-ai/ultimate --title "X_ISLAND_MODULE_DUPLICATED"   # paste this error\'s --json as the body: the framework bundled one of its own modules twice',
+  X_BACKFILL_SLICE_ENTITY:
+    'x errors explain X_BACKFILL_SLICE_ENTITY --json   # the refusal itself names the x g job line for this slice',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/path-segments.ts

@@ -12,3 +12,13 @@ export function pathSegments(path: string): readonly string[] {
 export function hasPathSegment(path: string, segment: string): boolean {
   return pathSegments(path).includes(segment);
 }
+
+/**
+ * Whether `path` lies strictly below `root`, on either separator. Bun resolves paths with a
+ * backslash on Windows, so `path.startsWith(`${root}/`)` was false for every file there: the dev
+ * reload graph recorded no import and no sheet as the app's own, and a save rendered stale code.
+ */
+export function isPathUnder(root: string, path: string): boolean {
+  const base = root.replaceAll('\\', '/').replace(/\/+$/, '');
+  return path.replaceAll('\\', '/').startsWith(`${base}/`);
+}

package/src/runtime-admin.ts

@@ -7,7 +7,7 @@ import type { AdminApp, AdminRouteConfig } from '@ultimat3/admin';
 import type { Route, RouteMeta } from '@ultimat3/http';
 import { asCtx, html, redirect, routeNotFound } from '@ultimat3/http';
 import type { RouteEntry } from '@ultimat3/render';
-import { compilePattern } from '@ultimat3/render';
+import { compilePattern, routeFor } from '@ultimat3/render';
 import { renderSsr } from '@ultimat3/render/server';
 import type { DocumentOptions } from './document-options';
 import { routeDocument } from './runtime-render';
@@ -120,6 +120,9 @@ const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
 
 const METHODS: readonly ('GET' | 'POST')[] = ['GET', 'POST'];
 
+/** A file route on a mounted path exists only by a claim the mount accepted (`registerRoute`). */
+const claimed = (path: string): boolean => routeFor(path) !== undefined;
+
 /**
  * Two paths per admin and two methods on each: the base path itself (the dashboard) and one
  * catch-all under it. The admin's own table is matched INSIDE the handler, against the table as
@@ -131,7 +134,11 @@ const METHODS: readonly ('GET' | 'POST')[] = ['GET', 'POST'];
 export function adminMountRoutes(options: AdminMountOptions): readonly Route[] {
   return [...declared().keys()].flatMap((base) =>
     [base, `${base}/*rest`].flatMap((path) =>
-      METHODS.map(
+      // The dashboard's GET, when an app file claimed it (`claimAdminRoute`): the file's route
+      // serves it, and two GETs on one path is X_ROUTE_CONFLICT. A claimed path UNDER the base
+      // needs nothing here — a static or param segment outranks the catch-all — and every POST
+      // stays the admin's. Only a claim the admin issued can put a file on a mounted path.
+      METHODS.filter((method) => !(method === 'GET' && path === base && claimed(base))).map(
         (method): Route => ({
           method,
           path,

package/src/runtime-assets.ts

@@ -179,7 +179,7 @@ async function mediaResponse(
 ): Promise<Response> {
   const requested = request.params['key'] ?? '';
   authorizeStorageRead({ disk: storage.defaultDisk, key: requested }, ctx);
-  const key = assertReadableKey(requested, ctx.actor);
+  const key = assertReadableKey(storage, storage.defaultDisk, requested, ctx.actor);
   const query = parseImageQuery(request.url.searchParams);
   if (query !== null) return transformedVariant(storage, key, query, images);
   // No transform asked for: the object itself, still under the storage key's own safety checks.

package/src/runtime-storage.ts

@@ -12,14 +12,22 @@ import { actorOf } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { asCtx, unauthenticated } from '@ultimat3/http';
 import type { KnownPermission } from '@ultimat3/policy';
-import { can, codeOf, evaluate, policyForbidden, reasonOf } from '@ultimat3/policy';
-import type { Storage, StorageRead } from '@ultimat3/storage';
+import {
+  can,
+  codeOf,
+  evaluate,
+  isKnownPermission,
+  policyForbidden,
+  reasonOf,
+} from '@ultimat3/policy';
+import type { Storage, StorageObject } from '@ultimat3/storage';
 import {
   assertSafeKey,
   DEFAULT_SIGNED_URL_BASE,
   definedStorage,
   isTenantScoped,
   isWithinOrg,
+  keyUnshared,
   objectNotFound,
   orgMismatch,
 } from '@ultimat3/storage';
@@ -30,8 +38,8 @@ import { storedObjectHeaders } from './stored-object-headers';
  * The one capability that gates reading a stored object, on every disk. A permission and not a
  * per-disk family: `disk` is in the policy's `input`, so an app that wants a per-disk rule writes
  * one predicate over it, while a second permission string would be a second thing to grant and to
- * forget. An app that declared a permission set without it gets `X_PERMISSION_UNKNOWN` from
- * `can()` — naming the exact `definePermissions` edit — rather than a request that quietly worked.
+ * forget. An app that declared a permission set without it serves nothing here: every read is a
+ * clean 401/403 (27.0.0; it was a 500 `X_PERMISSION_UNKNOWN`).
  */
 export const STORAGE_READ_PERMISSION = 'storage:read';
 
@@ -76,10 +84,22 @@ export interface StorageReadInput {
  */
 export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContext): void {
   const context = asCtx(ctx);
+  const actor = actorOf(context);
+  // An app that never declared `storage:read` serves nothing through this route: nobody can hold
+  // an undeclared permission, so it answers what a role without the grant gets — 401 for nobody,
+  // 403 for a known actor. `can()` would throw `X_PERMISSION_UNKNOWN` (500) here, and an app kept
+  // the permission declared-but-ungranted only to keep its own refusal a refusal.
+  if (!isKnownPermission(STORAGE_READ_PERMISSION)) {
+    if (actor === null) throw unauthenticated(ctx.url.pathname);
+    throw policyForbidden(
+      STORAGE_READ_PERMISSION,
+      `this app does not declare ${STORAGE_READ_PERMISSION}, so no role grants it`,
+    );
+  }
   // Built per request, not at mount: an app whose permission set lacks `storage:read` must get a
   // problem document on this route, not a boot that takes every other route down with it.
   const policy = can<StorageReadInput>(READ_PERMISSION);
-  const evaluation = evaluate(policy, { input, actor: actorOf(context) });
+  const evaluation = evaluate(policy, { input, actor });
   if (evaluation.allowed) return;
   // The decision's own code goes on the wire, never a flattened one: `can()` denies "nobody" with
   // X_UNAUTHENTICATED and a known actor with X_FORBIDDEN, and 401 and 403 are different
@@ -93,26 +113,50 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
 
 /**
  * The key half of the read decision, in the order that discloses least: a key that could escape its
- * prefix is refused before any tenant is named, and a key inside another tenant's prefix is 404
- * (never 403 — `error-map.ts` maps `X_STORAGE_ORG_MISMATCH` there so a refusal cannot confirm that
- * a key exists).
+ * prefix is refused before any tenant is named; a key inside another tenant's prefix is 404 (never
+ * 403 — `error-map.ts` maps `X_STORAGE_ORG_MISMATCH` there so a refusal cannot confirm that a key
+ * exists); and a key inside NO tenant's prefix is served only when the app shared it.
+ *
+ * That last clause is secure by default (27.0.0). The rule used to be "not another tenant's", which
+ * read every key outside `org/` as everybody's: an app's all-tenant export, raw webhook payloads
+ * and DSR archives were one GET away for any signed-in reader holding `storage:read`. A key no
+ * tenant owns is now `X_STORAGE_KEY_UNSHARED` (404) unless `defineStorage({ shared })` lists its
+ * prefix for this disk — decided from the key alone, so it too says nothing about existence.
  *
  * Split out of `readStorageObject` because `/media/*key` (`runtime-assets.ts`) has to make the same
  * decision and made none at all: it passed a client-supplied key straight to `disk().get`, so every
  * object on the app's only disk was one unauthenticated URL away. A second copy of this test is how
  * one of the two surfaces would drift back — `storage-surfaces.test.ts` is what holds them level.
  */
-export function assertReadableKey(key: string, actor: Actor): string {
+export function assertReadableKey(
+  storage: Storage,
+  disk: string,
+  key: string,
+  actor: Actor,
+): string {
   const safe = assertSafeKey(key);
   // An actor with no org is inside no org, so every tenant-scoped key is somebody else's —
   // `isWithinOrg` answers exactly that for an empty org, without throwing.
   const orgId = actor.orgId ?? '';
-  if (isTenantScoped(safe) && !isWithinOrg(safe, orgId)) {
-    throw orgMismatch(safe, orgId);
+  if (isTenantScoped(safe)) {
+    if (!isWithinOrg(safe, orgId)) throw orgMismatch(safe, orgId);
+    return safe;
   }
+  if (!storage.isShared(disk, safe)) throw keyUnshared(disk, safe);
   return safe;
 }
 
+/**
+ * What the route serves: the object's description and a STREAM of its bytes, never a buffer. The
+ * route used `get()`, which holds the whole object in memory and refuses past the disk's
+ * `maxGetBytes` — so a large upload was either a pod's worth of heap or `X_STORAGE_TOO_LARGE`.
+ */
+export interface ServedObject {
+  readonly object: StorageObject;
+  /** Opened only once the route knows it will send a body: a 304 and a 416 open nothing. */
+  readonly open: () => Promise<ReadableStream<Uint8Array>>;
+}
+
 /**
  * Everything between the decision and the bytes. An unknown disk is the same 404 the foreign-tenant
  * case answers, rather than `X_STORAGE_DISK_UNKNOWN`, whose cause lists every configured disk name.
@@ -121,10 +165,13 @@ export async function readStorageObject(
   storage: Storage,
   input: StorageReadInput,
   actor: Actor,
-): Promise<StorageRead> {
-  const key = assertReadableKey(input.key, actor);
+): Promise<ServedObject> {
+  const key = assertReadableKey(storage, input.disk, input.key, actor);
   if (!storage.diskNames.includes(input.disk)) throw objectNotFound(input.disk, key);
-  return storage.disk(input.disk).get(key);
+  const driver = storage.disk(input.disk);
+  const object = await driver.stat(key);
+  if (object === undefined) throw objectNotFound(input.disk, key);
+  return { object, open: () => driver.stream(key) };
 }
 
 /** Inclusive, as `Range` and `Content-Range` both are. */
@@ -174,24 +221,53 @@ export function etagMatches(header: string | null, etag: string): boolean {
   return header.split(',').some((candidate) => candidate.trim().replace(/^W\//, '') === etag);
 }
 
+/**
+ * The inclusive window `[start, end]` of a stream, as a stream. A disk streams from byte 0 (the
+ * driver contract has no ranged read), so the bytes before `start` are read and dropped: bounded
+ * memory, at the cost of reading the prefix — the trade a `Range` probe on a video wants over
+ * buffering the whole object.
+ */
+function windowOf(
+  source: ReadableStream<Uint8Array>,
+  start: number,
+  end: number,
+): ReadableStream<Uint8Array> {
+  let offset = 0;
+  return source.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        const from = Math.max(start - offset, 0);
+        const to = Math.min(end + 1 - offset, chunk.byteLength);
+        offset += chunk.byteLength;
+        if (to > from) controller.enqueue(chunk.subarray(from, to));
+        if (offset > end) controller.terminate();
+      },
+    }),
+  );
+}
+
 /**
  * The content type is the STORED one — the upload gate sniffed those bytes and `put` recorded the
  * answer, so an extension in the URL is the only party that can lie. The validator is the driver's
  * own content hash (local: sha256 of the bytes, S3: the provider's etag), which is the identity
  * storage already keeps for an object; inventing a cache key here would be a second one.
  */
-export function storageResponse(request: UltimateRequest, read: StorageRead): Response {
-  const etag = `"${read.object.etag}"`;
+export async function storageResponse(
+  request: UltimateRequest,
+  served: ServedObject,
+): Promise<Response> {
+  const { object } = served;
+  const etag = `"${object.etag}"`;
   const headers = new Headers({
-    'content-type': read.object.contentType,
+    'content-type': object.contentType,
     etag,
     'accept-ranges': 'bytes',
     // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
-    ...storedObjectHeaders(read.object.contentType),
+    ...storedObjectHeaders(object.contentType),
   });
   // Omitted, never invented: a disk whose provider reported no date has none, and a `Last-Modified`
   // made up for it is a validator a cache would go on to trust.
-  const modified = read.object.lastModified;
+  const modified = object.lastModified;
   if (modified !== undefined) headers.set('last-modified', modified.toUTCString());
   // Revalidation costs a request and no bytes, which is the trade an authorized response wants:
   // the bytes never change under a key, but the actor's permission to read them can be revoked.
@@ -199,23 +275,24 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
     return new Response(null, { status: 304, headers });
   }
 
-  const size = read.bytes.byteLength;
+  const size = object.size;
   const range = parseByteRange(request.header('range'), size);
   if (range === UNSATISFIABLE) {
     headers.set('content-range', `bytes */${size}`);
     return new Response(null, { status: 416, headers });
   }
-  // Copied at each call, not through a helper, for `runtime-assets.ts`'s reason: a
-  // `Uint8Array<ArrayBufferLike>` may be backed by a `SharedArrayBuffer`, which `Response` does
-  // not accept — and a helper's declared return type widens the copy back to the type it refuses.
+  // `size` is the stat's: a key's bytes never change under it (an upload mints a new key), so the
+  // length declared here is the length the stream delivers.
   if (range === undefined) {
     headers.set('content-length', String(size));
-    return new Response(new Uint8Array(read.bytes), { headers });
+    return new Response(await served.open(), { headers });
   }
-  const slice = read.bytes.subarray(range.start, range.end + 1);
   headers.set('content-range', `bytes ${range.start}-${range.end}/${size}`);
-  headers.set('content-length', String(slice.byteLength));
-  return new Response(new Uint8Array(slice), { status: 206, headers });
+  headers.set('content-length', String(range.end - range.start + 1));
+  return new Response(windowOf(await served.open(), range.start, range.end), {
+    status: 206,
+    headers,
+  });
 }
 
 /**
@@ -239,6 +316,7 @@ export function servedStorage(host: Storage): Storage {
       return current().diskNames;
     },
     disk: (name?: string) => current().disk(name),
+    isShared: (disk: string, key: string) => current().isShared(disk, key),
   };
 }
 

package/src/templates/backfill.ts

@@ -2,12 +2,13 @@
 // primitive, so it inherits .enqueue(), the retry policy, the cancellation and the manifest row.
 // One live run per name: a second enqueue while the pass is going is the same pass.
 
+import { stripComments, UltimateError } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
 import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
-import { sliceFoundation } from './slice-foundation';
+import { sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /**
@@ -226,11 +227,54 @@ unitTest('the projection is idempotent: a replayed page changes nothing', () =>
 export interface BackfillOptions extends FeatureTarget {
   /** Every locale the planted entity's admin labels ship for. Defaults to `['en']`. */
   readonly locales?: readonly string[];
+  /** The slice's `entity.ts` as it stands on disk, absent when the feature has none yet. */
+  readonly sliceEntity?: string;
+  /** The slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
+  readonly sliceRepo?: string;
+}
+
+/** Every table an `entity.ts` declares, in source order: `entity('court_closures', …)`. */
+const declaredTables = (source: string): readonly string[] =>
+  [...stripComments(source).matchAll(/\bentity\(\s*['"]([^'"]+)['"]/g)].map(
+    (match) => match[1] ?? '',
+  );
+
+/**
+ * Declared beside its one thrower: `errors.ts` sits at its ceiling. The sweep this generator writes
+ * reads the slice's OWN scaffolded table (`db.<plural>`, its `title` and `price`), so a slice whose
+ * entities are named otherwise — notificado.co's `deadline`, holding `holidays` and
+ * `court_closures` — got `import type { Deadline }`, `db.deadlines` and admin labels for a table
+ * that does not exist. Refused before a file is planned; a hand sweep starts from a job.
+ */
+export class BackfillSliceEntityError extends UltimateError {
+  constructor(input: {
+    readonly name: string;
+    readonly feature: string;
+    readonly tables: readonly string[];
+  }) {
+    const declared = input.tables.length === 0 ? 'no table' : input.tables.join(', ');
+    super({
+      code: 'X_BACKFILL_SLICE_ENTITY',
+      cause: `x g backfill sweeps the ${input.feature} slice's own scaffolded table, and its entity.ts declares ${declared} instead — the generated files would import a row type and a db handle that do not exist`,
+      fix: `x g job ${input.name} --feature ${input.feature}   # then declare backfill({ source: db.<one of: ${declared}>, … }) from @ultimat3/jobs in it`,
+      meta: { feature: input.feature, tables: [...input.tables] },
+    });
+  }
 }
 
 export function backfillFiles(rawName: string, target: BackfillOptions): readonly GeneratedFile[] {
   const name = names(rawName);
   const feature = names(target.feature);
+  if (
+    target.sliceEntity !== undefined &&
+    !sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo)
+  ) {
+    throw new BackfillSliceEntityError({
+      name: name.kebab,
+      feature: target.feature,
+      tables: declaredTables(target.sliceEntity),
+    });
+  }
   const dir = `${target.surfaceDir}/${target.feature}/backfills`;
   const dbModule = target.dbModule ?? PLACEHOLDER_DB_MODULE;
   return [