@takosjp/yurucommu-core 4.1.0 → 4.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [
@@ -59,8 +59,9 @@
     "start": "bun src/backend/server.ts",
     "dev": "bun src/backend/server.ts",
     "dev:server": "bun src/backend/server.ts",
-    "check": "bun run fmt:check && tsc --noEmit && bun run check:no-opentofu-artifacts && bun run test",
+    "check": "bun run fmt:check && tsc --noEmit && bun run check:no-opentofu-artifacts && bun run check:worker-bundle && bun run test",
     "check:no-opentofu-artifacts": "bun scripts/check-no-opentofu-artifacts.mjs",
+    "check:worker-bundle": "bun scripts/check-worker-bundle-portable.mjs",
     "test": "bun run build:api && bun test test/ src/backend/ packages/api/src/ scripts/check-publish-version-discipline.test.ts scripts/publish-package-resumable.test.ts && bun run check:release-contents",
     "test:backend": "bun test src/backend/",
     "build": "bun run build:api",

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/backend/runtime/bun.ts

@@ -24,7 +24,7 @@ import {
   assertPathChainWithinBasePath,
   isPathWithinBasePath,
   resolvePathWithinBasePath,
-} from "./shared.ts";
+} from "./node-paths.ts";
 import { MemoryKV } from "./memory-kv.ts";
 import { isBackendPath } from "../lib/backend-paths.ts";
 import { loadBunSqlite } from "./compat-bun/types.ts";

package/src/backend/runtime/edge-facades.ts

@@ -9,7 +9,7 @@
  * The managed Cloudflare backend and the self-host backend project the SAME
  * facade: same methods, same option keys, same error names. Takoserver's
  * ADR 0005 states this explicitly for object storage, and its self-host wrapper
- * repeats it for KV and SQL.
+ * repeats it for all four.
  *
  * This module is a TYPE MIRROR of that contract plus the structural probes the
  * lane selector uses. It deliberately contains no behaviour: the adapters that
@@ -21,7 +21,8 @@
  *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`,
  *       `createQueueAdapter`, `createEdgeObjectsR2Adapter`
  *   takoserver `src/providers/selfhost-worker-wrapper.ts`
- *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`
+ *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`,
+ *       `createQueueAdapter`, `createObjectsAdapter`
  *
  * Every method rejects with an `Error` whose `name` is the portable error code
  * (`invalid_key`, `invalid_value`, `value_too_large`, `metadata_too_large`,
@@ -235,22 +236,24 @@ function hasMethods(value: unknown, names: readonly string[]): boolean {
 /**
  * Structural probes.
  *
- * Only SOME bindings can be told apart by shape, and the difference matters:
+ * Only ONE binding can be told apart by shape, and the difference matters:
  *
  *   decisive   `DB`     — `execute`/`query`/`transaction` (facade) against
  *                         `prepare`/`batch` (D1). Disjoint method sets.
- *   decisive   `MEDIA`  — R2 carries the multipart helpers the facade omits.
  *   decisive   a queue *batch* — `acknowledgeAll` (facade) against `ackAll`
  *                         (Cloudflare `MessageBatch`).
  *   AMBIGUOUS  `KV`     — `edge.kv` and `KVNamespace` expose the same five
  *                         method names.
  *   AMBIGUOUS  a queue *producer* — both are `send`/`sendBatch`.
+ *   AMBIGUOUS  `MEDIA`  — `edge.objects@1.0.0` is R2's method set by design,
+ *                         multipart helpers included. See below.
  *
  * That is why the lane is a DECLARED variable rather than something sniffed:
- * two of the five bindings cannot be identified at all. The declaration is then
- * cross-checked against the decisive bindings, so a Worker whose var and whose
- * bindings disagree refuses to start instead of calling `kv.get(key, {type})`
- * on a facade that would silently treat the options object as nothing.
+ * three of the five bindings cannot be identified at all. The declaration is
+ * then cross-checked against the decisive bindings, so a Worker whose var and
+ * whose bindings disagree refuses to start instead of calling
+ * `kv.get(key, {type})` on a facade that would silently treat the options
+ * object as nothing.
  */
 export function isEdgeSqlBinding(value: unknown): value is EdgeSqlBinding {
   return (
@@ -274,24 +277,38 @@ export function isEdgeQueueBatch(value: unknown): value is EdgeQueueBatch {
   );
 }
 
+/**
+ * A bucket-shaped binding with `edge.objects@1.0.0`'s call signatures.
+ *
+ * NOT DECISIVE, and never a lane test. The facade is R2's method set on
+ * purpose — `head`, `get`, `put`, `delete`, `list`, and the four multipart
+ * calls — so that an app written against R2 ports over unchanged. A real
+ * `R2Bucket` therefore answers `true` here too. Use it to check that SOMETHING
+ * bucket-shaped arrived, never to decide which host projected it: that is what
+ * `YURUCOMMU_RUNTIME_LANE` is for.
+ *
+ * The arity check is the facade's own contract rather than a discriminator:
+ * the Host counts `arguments.length`, so `get` takes its options slot even when
+ * that slot is `undefined`.
+ */
 export function isEdgeObjectsBinding(
   value: unknown,
 ): value is EdgeObjectsBinding {
   return (
     hasMethods(value, ["head", "get", "put", "delete", "list"]) &&
-    // R2 exposes multipart helpers on the binding itself; the facade does not
-    // give a bucket-shaped object those names.
-    typeof (value as Record<string, unknown>).createMultipartUpload !==
-      "function" &&
-    // Arity is part of the facade's contract and is asserted rather than
-    // assumed: the Host checks `arguments.length`, so `get` and `list` take
-    // their options slot even when it is `undefined`. Anything bucket-shaped
-    // whose `get` takes one argument is some other adapter, not this facade.
     (value as { get: (...args: unknown[]) => unknown }).get.length === 2
   );
 }
 
-/** Cloudflare's `R2Bucket`. */
+/**
+ * Cloudflare's `R2Bucket` — and, unavoidably, the `edge.objects` facade.
+ *
+ * A method-name test cannot separate the two, because Takoserver's facade
+ * carries `createMultipartUpload` as well (`selfhost-worker-wrapper.ts`
+ * `createObjectsAdapter`). 4.1.0 used this function to refuse the portable
+ * lane and so refused every self-hosted deployment. Keep it for describing a
+ * binding; do not let it decide a lane.
+ */
 export function isNativeR2Bucket(value: unknown): boolean {
   return hasMethods(value, [
     "head",

package/src/backend/runtime/edge-objects.ts

@@ -21,10 +21,14 @@
  *  - NO ENUMERATION OR HEAD. The port does not carry them, so neither does the
  *    adapter, even though the Host projects both.
  *
- * AVAILABILITY: `edge.objects` is projected by the managed Cloudflare backend
- * (`createEdgeObjectsR2Adapter`). The self-host backend projects only
- * `edge.kv` and `edge.sql`, so a self-hosted Worker has no object binding and
- * the core's existing "object storage unavailable" behaviour applies.
+ * AVAILABILITY: BOTH wrapper backends project `edge.objects`. The managed
+ * Cloudflare backend does it over provider-private R2
+ * (`createEdgeObjectsR2Adapter`); the self-host backend realizes its own object
+ * store for a Version's `bucketBindings` and projects the same facade, byte for
+ * byte. A Worker on the `portable` lane therefore receives `env.MEDIA` on
+ * either host. What still leaves `MEDIA` unbound is a Version that declared no
+ * bucket at all, and the core's existing "object storage unavailable" (503)
+ * behaviour is what applies then.
  */
 
 import type {

package/src/backend/runtime/edge-queue.ts

@@ -14,12 +14,12 @@
  *    and the body arrives as `{encoding:"base64", data}`. `retry` also refuses
  *    `delaySeconds: 0`, which Cloudflare accepts as "no delay".
  *
- * AVAILABILITY: the managed Cloudflare backend projects queue bindings; the
- * self-host backend projects only `edge.kv` and `edge.sql` today (see
- * takoserver `selfhost-worker-wrapper.ts` `projectEnv`). A self-hosted Worker
- * therefore has no queue binding at all, and the core's existing behaviour for
- * an unbound `DELIVERY_QUEUE` — synchronous fallback delivery, reported by the
- * readiness surface — is what applies there.
+ * AVAILABILITY: both wrapper backends project queue bindings (see takoserver
+ * `selfhost-worker-wrapper.ts` `projectEnv`, whose data-binding kinds are
+ * `edge.kv`, `edge.objects`, `edge.queue` and `edge.sql`). What leaves
+ * `DELIVERY_QUEUE` unbound is a Version that declared no queue, and the core's
+ * existing behaviour for that — synchronous fallback delivery, reported by the
+ * readiness surface — is what applies then.
  */
 
 import {

package/src/backend/runtime/lane.ts

@@ -28,8 +28,18 @@
  * So the lane comes from `YURUCOMMU_RUNTIME_LANE`, which a self-host or managed
  * Workers-for-Platforms deployment sets to `portable` and every raw-binding
  * deployment leaves unset (or `cloudflare`). The declaration is then
- * cross-checked against the bindings that ARE decisive — `DB` always, `MEDIA`
- * when it is bound. A disagreement refuses to start.
+ * cross-checked against the ONE binding that is decisive — `DB`. A
+ * disagreement refuses to start.
+ *
+ * `MEDIA` is NOT decisive and must never be cross-checked. Takoserver's
+ * `edge.objects@1.0.0` facade is method-for-method a bucket: `head`, `get`,
+ * `put`, `delete`, `list`, `createMultipartUpload`, `uploadPart`,
+ * `completeMultipartUpload`, `abortMultipartUpload` — the same names, the same
+ * option keys, deliberately, so that an app written against R2 ports over
+ * unchanged (ADR 0005/0007). 4.1.0 read that identity backwards and refused the
+ * portable lane whenever `MEDIA` looked R2-shaped, which is to say always: a
+ * self-hosted Yurucommu Worker could not boot on the lane its own README
+ * documents. The declaration decides `MEDIA`.
  */
 
 import type {
@@ -47,7 +57,6 @@ import {
   isEdgeQueueBatch,
   isEdgeSqlBinding,
   isNativeD1Database,
-  isNativeR2Bucket,
   type EdgeKvBinding,
   type EdgeObjectsBinding,
   type EdgeQueueBatch,
@@ -114,23 +123,35 @@ export function resolveRuntimeLane(declared: unknown): RuntimeLane {
 
 interface LaneBindings {
   readonly DB?: unknown;
+  /**
+   * Accepted so a caller can pass the whole `env`, and deliberately not read:
+   * the bucket binding carries no evidence about the lane. See
+   * {@link assertRuntimeLaneBindings}.
+   */
   readonly MEDIA?: unknown;
 }
 
 /**
- * Prove the declared lane against the bindings that can actually be identified.
+ * Prove the declared lane against the ONE binding that can be identified.
+ *
+ * `DB` is decisive in both directions: `execute`/`query`/`transaction` and
+ * `prepare`/`batch` are disjoint method sets, so a Worker that was handed the
+ * wrong one would fail at its first query anyway and is better stopped here
+ * with a message that names the variable to fix.
  *
- * `DB` is always decisive: `execute`/`query`/`transaction` and
- * `prepare`/`batch` are disjoint. `MEDIA` is decisive only in one direction —
- * an `R2Bucket` is recognisable by its multipart helpers, whereas a plain
- * five-method object could be the facade or an adapter a host repository
- * supplied — so only the direction that can be proven is checked.
+ * `MEDIA` is checked against NOTHING. The portable `edge.objects@1.0.0` facade
+ * is intentionally indistinguishable from an `R2Bucket` — that identity is the
+ * point of the Interface — so a shape test on it can only produce false
+ * refusals. On `portable` the bucket is wrapped as the facade, on `cloudflare`
+ * as native R2, and the declaration is the whole of the evidence. Getting it
+ * wrong is loud and immediate (the first `MEDIA` call throws), not the silent
+ * misread that `KV`'s ambiguity would cause.
  */
 export function assertRuntimeLaneBindings(
   lane: RuntimeLane,
   bindings: LaneBindings,
 ): void {
-  const { DB, MEDIA } = bindings;
+  const { DB } = bindings;
   if (lane === "portable") {
     if (isNativeD1Database(DB)) {
       throw new RuntimeLaneError(
@@ -148,13 +169,6 @@ export function assertRuntimeLaneBindings(
           `neither that nor D1's prepare/batch.`,
       );
     }
-    if (MEDIA !== undefined && isNativeR2Bucket(MEDIA)) {
-      throw new RuntimeLaneError(
-        `${RUNTIME_LANE_VAR}="portable" declares the portable-facade lane, ` +
-          `but env.MEDIA is a native R2Bucket. A portable bucket binding ` +
-          `arrives as the edge.objects@1.0.0 facade.`,
-      );
-    }
     return;
   }
   if (isEdgeSqlBinding(DB)) {
@@ -287,5 +301,9 @@ export function wrapRuntimeMessageBatch<T>(
   return wrapCloudflareMessageBatch(batch as MessageBatch<T>);
 }
 
-/** Re-exported so a Worker entry can probe MEDIA without importing internals. */
+/**
+ * Re-exported so a Worker entry can assert that SOMETHING bucket-shaped
+ * arrived without importing internals. It does not identify the lane — a
+ * native `R2Bucket` satisfies it too — so never branch on it.
+ */
 export { isEdgeObjectsBinding };

package/src/backend/runtime/node-paths.ts

@@ -0,0 +1,79 @@
+/**
+ * Filesystem path containment for the Bun/Node runtime ONLY.
+ *
+ * These helpers need `node:path`, so they live apart from `shared.ts`. That
+ * separation is load-bearing rather than tidy: `shared.ts` is reached from
+ * `edge-kv.ts` and `edge-objects.ts`, which are on the portable Worker's
+ * import path. A `node:` specifier anywhere in that graph survives bundling as
+ * a real static import, and a wrapper host (self-hosted Takoserver, managed
+ * Workers-for-Platforms) runs the Worker with no `nodejs_compat` flag — the
+ * portable `WorkerVersion` form has nowhere to ask for one — so the module
+ * fails to load with `No such module "node:path"` before a single request is
+ * served. Nothing in this file may be imported from a module the Worker
+ * bundle reaches; `scripts/check-worker-bundle-portable.mjs` enforces that.
+ */
+
+import path from "node:path";
+
+import { hasNulByte } from "./shared.ts";
+
+export function isPathWithinBasePath(
+  basePath: string,
+  candidatePath: string,
+): boolean {
+  const relative = path.relative(basePath, candidatePath);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+export function resolvePathWithinBasePath(
+  basePath: string,
+  key: string,
+): string {
+  if (hasNulByte(key)) {
+    throw new Error("Invalid path");
+  }
+  const resolvedPath = path.resolve(basePath, key);
+  if (!isPathWithinBasePath(basePath, resolvedPath)) {
+    throw new Error("Path escapes base directory");
+  }
+  return resolvedPath;
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+export async function assertPathChainWithinBasePath(
+  basePath: string,
+  targetPath: string,
+  realpath: (path: string) => Promise<string>,
+): Promise<void> {
+  let currentPath = targetPath;
+
+  while (true) {
+    try {
+      const realCurrentPath = await realpath(currentPath);
+      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
+        throw new Error("Path escapes base directory");
+      }
+      return;
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+      const parentPath = path.dirname(currentPath);
+      if (parentPath === currentPath) {
+        throw error;
+      }
+      currentPath = parentPath;
+    }
+  }
+}

package/src/backend/runtime/shared.ts

@@ -1,4 +1,12 @@
-import path from "node:path";
+/**
+ * Runtime helpers shared by EVERY lane, including the portable Worker.
+ *
+ * `edge-kv.ts` and `edge-objects.ts` import this module, so it is part of the
+ * bundle a wrapper host loads with no `nodejs_compat` flag. It must therefore
+ * stay free of `node:` specifiers; the filesystem path helpers that need
+ * `node:path` live in `node-paths.ts`, which only the Bun/Node runtime
+ * imports.
+ */
 
 export const DEFAULT_LIST_LIMIT = 1000;
 
@@ -35,67 +43,6 @@ export function hasNulByte(value: string): boolean {
   return value.includes("\0");
 }
 
-export function isPathWithinBasePath(
-  basePath: string,
-  candidatePath: string,
-): boolean {
-  const relative = path.relative(basePath, candidatePath);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-export function resolvePathWithinBasePath(
-  basePath: string,
-  key: string,
-): string {
-  if (hasNulByte(key)) {
-    throw new Error("Invalid path");
-  }
-  const resolvedPath = path.resolve(basePath, key);
-  if (!isPathWithinBasePath(basePath, resolvedPath)) {
-    throw new Error("Path escapes base directory");
-  }
-  return resolvedPath;
-}
-
-function isNotFoundError(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    (error as { code?: unknown }).code === "ENOENT"
-  );
-}
-
-export async function assertPathChainWithinBasePath(
-  basePath: string,
-  targetPath: string,
-  realpath: (path: string) => Promise<string>,
-): Promise<void> {
-  let currentPath = targetPath;
-
-  while (true) {
-    try {
-      const realCurrentPath = await realpath(currentPath);
-      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
-        throw new Error("Path escapes base directory");
-      }
-      return;
-    } catch (error) {
-      if (!isNotFoundError(error)) {
-        throw error;
-      }
-      const parentPath = path.dirname(currentPath);
-      if (parentPath === currentPath) {
-        throw error;
-      }
-      currentPath = parentPath;
-    }
-  }
-}
-
 export async function readStream(
   stream: ReadableStream<Uint8Array>,
 ): Promise<Uint8Array> {