@tangen/porter 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @tangen/porter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Porter is Tangen's data movement product: promote content between
+environments, export/import portable bundles, and transfer directly between
+instances. A porter carries your goods safely between places - and data
+portability is the promise.
+
+Optional extension package. Install only when you want the Export/Import
+surfaces; environment promotion plumbing lives in the platform core.

package/dist/bundle.d.ts

@@ -0,0 +1,63 @@
+/**
+ * File Name: bundle.ts
+ * Purpose: The Porter bundle format (E-T1) - the portable shape of a Tangen
+ *   export. A bundle is a storage prefix holding streaming JSONL SECTIONS
+ *   (objects per type, media index, custom tables, ...) in immutable parts,
+ *   plus raw media files, sealed by a manifest written LAST: the manifest's
+ *   presence is the completeness marker, and it records the schema
+ *   fingerprint the import side diffs before writing anything.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Only @tangen/types (StorageAdapter). Parts mirror the
+ *   run-ledger design: storage backends have no append, so each flush is one
+ *   immutable file - nothing is ever buffered beyond flushEvery entries.
+ *   Layout under porter/bundles/<bundleId>/:
+ *     manifest.json
+ *     <section>-<part>.jsonl        e.g. objects/page-0.jsonl
+ *     media/files/<assetId>/<file>  raw bytes
+ */
+import type { StorageAdapter } from '@tangen/types';
+export declare const BUNDLE_FORMAT_VERSION = "1.0.0";
+export interface BundleManifest {
+    formatVersion: string;
+    workspaceId: string;
+    sourceEnvId: string | null;
+    createdAt: string;
+    createdBy: string | null;
+    /** Field-level schema fingerprint of the exported types (schema-diff shape). */
+    schema: unknown[];
+    /** section name -> number of JSONL parts. */
+    sections: Record<string, number>;
+    /** section name -> number of entries. */
+    counts: Record<string, number>;
+    [key: string]: unknown;
+}
+export interface BundleSectionWriter {
+    append(entry: Record<string, unknown>): void;
+    /** Writes buffered entries as one immutable part. */
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface BundleWriter {
+    section(name: string): BundleSectionWriter;
+    writeMediaFile(assetId: string, filename: string, bytes: Uint8Array, contentType?: string): Promise<void>;
+    /** Writes the manifest LAST - sealing marks the bundle complete. */
+    seal(manifest: Omit<BundleManifest, 'formatVersion' | 'sections' | 'counts'>): Promise<void>;
+}
+export declare function createBundleWriter(storage: StorageAdapter, bundleId: string, opts?: {
+    flushEvery?: number;
+}): BundleWriter;
+/**
+ * Refuses bundles this build cannot understand: absent formatVersion, or a
+ * MAJOR newer than ours. Older majors pass through to documented shims.
+ */
+export declare function assertSupportedFormat(manifest: Pick<BundleManifest, 'formatVersion'>): void;
+export interface BundleReader {
+    manifest: BundleManifest;
+    readSection(name: string): AsyncGenerator<Record<string, unknown>>;
+    readMediaFile(assetId: string, filename: string): Promise<Uint8Array | null>;
+}
+/** Opens a SEALED bundle; an absent manifest means incomplete -> refuse. */
+export declare function openBundleReader(storage: StorageAdapter, bundleId: string): Promise<BundleReader>;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * File Name: index.ts
+ * Purpose: @tangen/porter public surface - the data movement product.
+ *   E-T1 ships the bundle format; exporters, importers and the remote
+ *   transport land in their arcs.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+export { createBundleWriter, openBundleReader, assertSupportedFormat, BUNDLE_FORMAT_VERSION, type BundleManifest, type BundleWriter, type BundleReader, type BundleSectionWriter, } from './bundle';
+export { bundleKeys, tarGzBundle, untarGz, importBundleFromTarGz, type TarEntry } from './tar';

package/dist/index.js

@@ -0,0 +1,225 @@
+// src/bundle.ts
+var BUNDLE_FORMAT_VERSION = "1.0.0";
+var prefix = (bundleId) => `porter/bundles/${bundleId}`;
+var partKey = (bundleId, section, part) => `${prefix(bundleId)}/${section}-${part}.jsonl`;
+var manifestKey = (bundleId) => `${prefix(bundleId)}/manifest.json`;
+var mediaFileKey = (bundleId, assetId, filename) => `${prefix(bundleId)}/media/files/${assetId}/${filename}`;
+function createBundleWriter(storage, bundleId, opts = {}) {
+  const flushEvery = opts.flushEvery ?? 500;
+  const sections = {};
+  const counts = {};
+  let sealed = false;
+  function section(name) {
+    sections[name] ??= 0;
+    counts[name] ??= 0;
+    let buffer = [];
+    let pending = Promise.resolve();
+    function flush() {
+      if (buffer.length > 0) {
+        const entries = buffer;
+        buffer = [];
+        const part = sections[name];
+        sections[name] += 1;
+        counts[name] += entries.length;
+        const lines = entries.map((e) => JSON.stringify(e)).join(`
+`) + `
+`;
+        pending = pending.then(() => storage.write(partKey(bundleId, name, part), new TextEncoder().encode(lines), {
+          contentType: "application/x-ndjson"
+        }));
+      }
+      return pending;
+    }
+    return {
+      append(entry) {
+        buffer.push(entry);
+        if (buffer.length >= flushEvery)
+          flush();
+      },
+      flush,
+      close: flush
+    };
+  }
+  return {
+    section,
+    async writeMediaFile(assetId, filename, bytes, contentType) {
+      await storage.write(mediaFileKey(bundleId, assetId, filename), bytes, { contentType });
+    },
+    async seal(manifest) {
+      if (sealed)
+        throw new Error(`bundle ${bundleId} is already sealed`);
+      sealed = true;
+      const full = {
+        ...manifest,
+        formatVersion: BUNDLE_FORMAT_VERSION,
+        sections: { ...sections },
+        counts: { ...counts }
+      };
+      await storage.write(manifestKey(bundleId), new TextEncoder().encode(JSON.stringify(full, null, 2)), {
+        contentType: "application/json"
+      });
+    }
+  };
+}
+function assertSupportedFormat(manifest) {
+  const version = manifest.formatVersion;
+  if (!version || typeof version !== "string") {
+    throw new Error("bundle manifest has no formatVersion - not a Tangen export");
+  }
+  const major = Number(version.split(".")[0]);
+  const ourMajor = Number(BUNDLE_FORMAT_VERSION.split(".")[0]);
+  if (!Number.isFinite(major) || major > ourMajor) {
+    throw new Error(`bundle format ${version} is newer than this platform understands (${BUNDLE_FORMAT_VERSION}) - update the platform before importing`);
+  }
+}
+async function openBundleReader(storage, bundleId) {
+  const raw = await storage.read(manifestKey(bundleId));
+  if (!raw) {
+    throw new Error(`bundle ${bundleId} has no manifest - it is incomplete or was never sealed`);
+  }
+  const manifest = JSON.parse(new TextDecoder().decode(raw));
+  return {
+    manifest,
+    async* readSection(name) {
+      const parts = manifest.sections[name] ?? 0;
+      const decoder = new TextDecoder;
+      for (let part = 0;part < parts; part++) {
+        const bytes = await storage.read(partKey(bundleId, name, part));
+        if (!bytes)
+          continue;
+        for (const line of decoder.decode(bytes).split(`
+`)) {
+          if (line.trim())
+            yield JSON.parse(line);
+        }
+      }
+    },
+    readMediaFile(assetId, filename) {
+      return storage.read(mediaFileKey(bundleId, assetId, filename));
+    }
+  };
+}
+// src/tar.ts
+import { gzipSync, gunzipSync } from "node:zlib";
+var prefix2 = (bundleId) => `porter/bundles/${bundleId}`;
+async function bundleKeys(storage, bundleId) {
+  const reader = await openBundleReader(storage, bundleId);
+  const keys = ["manifest.json"];
+  for (const [section, parts] of Object.entries(reader.manifest.sections)) {
+    for (let part = 0;part < parts; part++)
+      keys.push(`${section}-${part}.jsonl`);
+  }
+  for await (const entry of reader.readSection("media/index")) {
+    const asset = entry.asset;
+    const filename = entry.filename;
+    if (asset?.id && filename)
+      keys.push(`media/files/${asset.id}/${filename}`);
+  }
+  return keys;
+}
+function octal(value, length) {
+  const s = value.toString(8).padStart(length - 1, "0") + "\x00";
+  return new TextEncoder().encode(s);
+}
+function tarHeader(name, size, mtime) {
+  const header = new Uint8Array(512);
+  const enc = new TextEncoder;
+  let fileName = name;
+  let filePrefix = "";
+  if (fileName.length > 100) {
+    const cut = fileName.lastIndexOf("/", 155);
+    if (cut <= 0)
+      throw new Error(`tar: path too long and unsplittable: ${name}`);
+    filePrefix = fileName.slice(0, cut);
+    fileName = fileName.slice(cut + 1);
+    if (fileName.length > 100 || filePrefix.length > 155) {
+      throw new Error(`tar: path too long: ${name}`);
+    }
+  }
+  header.set(enc.encode(fileName), 0);
+  header.set(octal(420, 8), 100);
+  header.set(octal(0, 8), 108);
+  header.set(octal(0, 8), 116);
+  header.set(octal(size, 12), 124);
+  header.set(octal(mtime, 12), 136);
+  header.set(enc.encode("        "), 148);
+  header[156] = 48;
+  header.set(enc.encode("ustar\x00"), 257);
+  header.set(enc.encode("00"), 263);
+  header.set(enc.encode(filePrefix), 345);
+  let checksum = 0;
+  for (const byte of header)
+    checksum += byte;
+  const cs = checksum.toString(8).padStart(6, "0") + "\x00 ";
+  header.set(enc.encode(cs), 148);
+  return header;
+}
+async function tarGzBundle(storage, bundleId, opts = {}) {
+  const mtime = opts.mtime ?? 0;
+  const keys = (await bundleKeys(storage, bundleId)).filter((k) => !opts.excludePrefix || !k.startsWith(opts.excludePrefix));
+  const chunks = [];
+  for (const key of keys) {
+    const bytes = await storage.read(`${prefix2(bundleId)}/${key}`);
+    if (!bytes)
+      throw new Error(`bundle ${bundleId} is missing "${key}" - refusing to package an incomplete archive`);
+    chunks.push(tarHeader(key, bytes.byteLength, mtime));
+    chunks.push(bytes);
+    const pad = (512 - bytes.byteLength % 512) % 512;
+    if (pad > 0)
+      chunks.push(new Uint8Array(pad));
+  }
+  chunks.push(new Uint8Array(1024));
+  const total = chunks.reduce((n, c) => n + c.byteLength, 0);
+  const tar = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    tar.set(c, offset);
+    offset += c.byteLength;
+  }
+  return new Uint8Array(gzipSync(tar));
+}
+function untarGz(archive) {
+  const tar = new Uint8Array(gunzipSync(archive));
+  const dec = new TextDecoder;
+  const entries = [];
+  let offset = 0;
+  while (offset + 512 <= tar.byteLength) {
+    const block = tar.subarray(offset, offset + 512);
+    if (block.every((b) => b === 0))
+      break;
+    const name = dec.decode(block.subarray(0, 100)).replace(/\0.*$/, "");
+    const prefixField = dec.decode(block.subarray(345, 500)).replace(/\0.*$/, "");
+    const size = parseInt(dec.decode(block.subarray(124, 136)).replace(/\0.*$/, "").trim() || "0", 8);
+    const typeflag = block[156];
+    offset += 512;
+    const path = prefixField ? `${prefixField}/${name}` : name;
+    if (typeflag === 48 || typeflag === 0) {
+      entries.push({ path, bytes: tar.slice(offset, offset + size) });
+    }
+    offset += Math.ceil(size / 512) * 512;
+  }
+  return entries;
+}
+async function importBundleFromTarGz(storage, bundleId, archive) {
+  const entries = untarGz(archive);
+  if (!entries.some((e) => e.path === "manifest.json")) {
+    throw new Error("archive has no manifest.json - not a sealed Tangen export");
+  }
+  for (const entry of entries) {
+    if (entry.path.includes("..") || entry.path.startsWith("/")) {
+      throw new Error(`archive entry escapes the bundle: ${entry.path}`);
+    }
+    await storage.write(`${prefix2(bundleId)}/${entry.path}`, entry.bytes);
+  }
+  return bundleId;
+}
+export {
+  untarGz,
+  tarGzBundle,
+  openBundleReader,
+  importBundleFromTarGz,
+  createBundleWriter,
+  bundleKeys,
+  assertSupportedFormat,
+  BUNDLE_FORMAT_VERSION
+};

package/dist/tar.d.ts

@@ -0,0 +1,24 @@
+import type { StorageAdapter } from '@tangen/types';
+/**
+ * Every storage key of a sealed bundle, RELATIVE to the bundle root:
+ * manifest.json, each section part, each media file from media/index.
+ */
+export declare function bundleKeys(storage: StorageAdapter, bundleId: string): Promise<string[]>;
+/** One .tar.gz of the whole sealed bundle. `excludePrefix` leaves keys out
+ *  (R-T5: media bytes skip the wire when they travel by presigned URL). */
+export declare function tarGzBundle(storage: StorageAdapter, bundleId: string, opts?: {
+    mtime?: number;
+    excludePrefix?: string;
+}): Promise<Uint8Array>;
+export interface TarEntry {
+    path: string;
+    bytes: Uint8Array;
+}
+/** Extracts regular files from a .tar.gz (ustar incl. prefix field). */
+export declare function untarGz(archive: Uint8Array): TarEntry[];
+/**
+ * Writes an uploaded .tar.gz into storage as a bundle under `bundleId`.
+ * Refuses archives without a manifest (they were never sealed) and entries
+ * that escape the bundle prefix.
+ */
+export declare function importBundleFromTarGz(storage: StorageAdapter, bundleId: string, archive: Uint8Array): Promise<string>;

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@tangen/porter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Porter - data movement for Tangen CMS: promote, export/import bundles, remote transfer. A porter carries your goods safely between places.",
+  "homepage": "https://github.com/raghunathj/tangen#readme",
+  "bugs": {
+    "url": "https://github.com/raghunathj/tangen/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raghunathj/tangen.git",
+    "directory": "packages/porter"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__/**",
+    "!**/*.test.ts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir dist --target node --format esm --packages external && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@tangen/types": "^0.3.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,178 @@
+/**
+ * File Name: bundle.ts
+ * Purpose: The Porter bundle format (E-T1) - the portable shape of a Tangen
+ *   export. A bundle is a storage prefix holding streaming JSONL SECTIONS
+ *   (objects per type, media index, custom tables, ...) in immutable parts,
+ *   plus raw media files, sealed by a manifest written LAST: the manifest's
+ *   presence is the completeness marker, and it records the schema
+ *   fingerprint the import side diffs before writing anything.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Only @tangen/types (StorageAdapter). Parts mirror the
+ *   run-ledger design: storage backends have no append, so each flush is one
+ *   immutable file - nothing is ever buffered beyond flushEvery entries.
+ *   Layout under porter/bundles/<bundleId>/:
+ *     manifest.json
+ *     <section>-<part>.jsonl        e.g. objects/page-0.jsonl
+ *     media/files/<assetId>/<file>  raw bytes
+ */
+import type { StorageAdapter } from '@tangen/types'
+
+export const BUNDLE_FORMAT_VERSION = '1.0.0'
+
+export interface BundleManifest {
+  formatVersion: string
+  workspaceId: string
+  sourceEnvId: string | null
+  createdAt: string
+  createdBy: string | null
+  /** Field-level schema fingerprint of the exported types (schema-diff shape). */
+  schema: unknown[]
+  /** section name -> number of JSONL parts. */
+  sections: Record<string, number>
+  /** section name -> number of entries. */
+  counts: Record<string, number>
+  [key: string]: unknown
+}
+
+export interface BundleSectionWriter {
+  append(entry: Record<string, unknown>): void
+  /** Writes buffered entries as one immutable part. */
+  flush(): Promise<void>
+  close(): Promise<void>
+}
+
+export interface BundleWriter {
+  section(name: string): BundleSectionWriter
+  writeMediaFile(assetId: string, filename: string, bytes: Uint8Array, contentType?: string): Promise<void>
+  /** Writes the manifest LAST - sealing marks the bundle complete. */
+  seal(manifest: Omit<BundleManifest, 'formatVersion' | 'sections' | 'counts'>): Promise<void>
+}
+
+const prefix = (bundleId: string) => `porter/bundles/${bundleId}`
+const partKey = (bundleId: string, section: string, part: number) =>
+  `${prefix(bundleId)}/${section}-${part}.jsonl`
+const manifestKey = (bundleId: string) => `${prefix(bundleId)}/manifest.json`
+const mediaFileKey = (bundleId: string, assetId: string, filename: string) =>
+  `${prefix(bundleId)}/media/files/${assetId}/${filename}`
+
+export function createBundleWriter(
+  storage: StorageAdapter,
+  bundleId: string,
+  opts: { flushEvery?: number } = {},
+): BundleWriter {
+  const flushEvery = opts.flushEvery ?? 500
+  const sections: Record<string, number> = {}
+  const counts: Record<string, number> = {}
+  let sealed = false
+
+  function section(name: string): BundleSectionWriter {
+    sections[name] ??= 0
+    counts[name] ??= 0
+    let buffer: Record<string, unknown>[] = []
+    // Part numbers are assigned SYNCHRONOUSLY and writes are serialized on a
+    // chain - an auto-flush racing a close() must never share a part index.
+    let pending: Promise<void> = Promise.resolve()
+
+    function flush(): Promise<void> {
+      if (buffer.length > 0) {
+        const entries = buffer
+        buffer = []
+        const part = sections[name]
+        sections[name] += 1
+        counts[name] += entries.length
+        const lines = entries.map((e) => JSON.stringify(e)).join('\n') + '\n'
+        pending = pending.then(() =>
+          storage.write(partKey(bundleId, name, part), new TextEncoder().encode(lines), {
+            contentType: 'application/x-ndjson',
+          }),
+        )
+      }
+      return pending
+    }
+
+    return {
+      append(entry) {
+        buffer.push(entry)
+        if (buffer.length >= flushEvery) void flush()
+      },
+      flush,
+      close: flush,
+    }
+  }
+
+  return {
+    section,
+    async writeMediaFile(assetId, filename, bytes, contentType) {
+      await storage.write(mediaFileKey(bundleId, assetId, filename), bytes, { contentType })
+    },
+    async seal(manifest) {
+      if (sealed) throw new Error(`bundle ${bundleId} is already sealed`)
+      sealed = true
+      // Omit over an index-signature type erases the known keys, so the
+      // spread needs an assertion to reassemble the full manifest shape.
+      const full = {
+        ...manifest,
+        formatVersion: BUNDLE_FORMAT_VERSION,
+        sections: { ...sections },
+        counts: { ...counts },
+      } as BundleManifest
+      await storage.write(manifestKey(bundleId), new TextEncoder().encode(JSON.stringify(full, null, 2)), {
+        contentType: 'application/json',
+      })
+    },
+  }
+}
+
+/**
+ * Refuses bundles this build cannot understand: absent formatVersion, or a
+ * MAJOR newer than ours. Older majors pass through to documented shims.
+ */
+export function assertSupportedFormat(manifest: Pick<BundleManifest, 'formatVersion'>): void {
+  const version = manifest.formatVersion
+  if (!version || typeof version !== 'string') {
+    throw new Error('bundle manifest has no formatVersion - not a Tangen export')
+  }
+  const major = Number(version.split('.')[0])
+  const ourMajor = Number(BUNDLE_FORMAT_VERSION.split('.')[0])
+  if (!Number.isFinite(major) || major > ourMajor) {
+    throw new Error(
+      `bundle format ${version} is newer than this platform understands (${BUNDLE_FORMAT_VERSION}) - update the platform before importing`,
+    )
+  }
+}
+
+export interface BundleReader {
+  manifest: BundleManifest
+  readSection(name: string): AsyncGenerator<Record<string, unknown>>
+  readMediaFile(assetId: string, filename: string): Promise<Uint8Array | null>
+}
+
+/** Opens a SEALED bundle; an absent manifest means incomplete -> refuse. */
+export async function openBundleReader(storage: StorageAdapter, bundleId: string): Promise<BundleReader> {
+  const raw = await storage.read(manifestKey(bundleId))
+  if (!raw) {
+    throw new Error(`bundle ${bundleId} has no manifest - it is incomplete or was never sealed`)
+  }
+  const manifest = JSON.parse(new TextDecoder().decode(raw)) as BundleManifest
+
+  return {
+    manifest,
+    async *readSection(name) {
+      const parts = manifest.sections[name] ?? 0
+      const decoder = new TextDecoder()
+      for (let part = 0; part < parts; part++) {
+        const bytes = await storage.read(partKey(bundleId, name, part))
+        if (!bytes) continue
+        for (const line of decoder.decode(bytes).split('\n')) {
+          if (line.trim()) yield JSON.parse(line)
+        }
+      }
+    },
+    readMediaFile(assetId, filename) {
+      return storage.read(mediaFileKey(bundleId, assetId, filename))
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * File Name: index.ts
+ * Purpose: @tangen/porter public surface - the data movement product.
+ *   E-T1 ships the bundle format; exporters, importers and the remote
+ *   transport land in their arcs.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ */
+export {
+  createBundleWriter, openBundleReader, assertSupportedFormat, BUNDLE_FORMAT_VERSION,
+  type BundleManifest, type BundleWriter, type BundleReader, type BundleSectionWriter,
+} from './bundle'
+export { bundleKeys, tarGzBundle, untarGz, importBundleFromTarGz, type TarEntry } from './tar'

package/src/tar.ts

@@ -0,0 +1,160 @@
+/**
+ * File Name: tar.ts
+ * Purpose: Packages a sealed bundle as one downloadable .tar.gz - the
+ *   portable file people move between machines and instances. Zero
+ *   dependencies: hand-rolled ustar headers + node:zlib gzip. Storage
+ *   adapters cannot enumerate keys, so the file list derives entirely from
+ *   the manifest (sections x parts + media/index entries).
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: ustar handles paths <= 100 chars directly; longer
+ *   paths use the prefix field (<= 155 + 100), which covers every key shape
+ *   Porter generates. Entries are regular files, mode 0644, deterministic
+ *   given an mtime.
+ */
+import { gzipSync, gunzipSync } from 'node:zlib'
+import type { StorageAdapter } from '@tangen/types'
+import { openBundleReader } from './bundle'
+
+const prefix = (bundleId: string) => `porter/bundles/${bundleId}`
+
+/**
+ * Every storage key of a sealed bundle, RELATIVE to the bundle root:
+ * manifest.json, each section part, each media file from media/index.
+ */
+export async function bundleKeys(storage: StorageAdapter, bundleId: string): Promise<string[]> {
+  const reader = await openBundleReader(storage, bundleId)
+  const keys: string[] = ['manifest.json']
+  for (const [section, parts] of Object.entries(reader.manifest.sections)) {
+    for (let part = 0; part < parts; part++) keys.push(`${section}-${part}.jsonl`)
+  }
+  for await (const entry of reader.readSection('media/index')) {
+    const asset = (entry as any).asset
+    const filename = (entry as any).filename
+    if (asset?.id && filename) keys.push(`media/files/${asset.id}/${filename}`)
+  }
+  return keys
+}
+
+function octal(value: number, length: number): Uint8Array {
+  const s = value.toString(8).padStart(length - 1, '0') + '\0'
+  return new TextEncoder().encode(s)
+}
+
+function tarHeader(name: string, size: number, mtime: number): Uint8Array {
+  const header = new Uint8Array(512)
+  const enc = new TextEncoder()
+
+  // Long paths: split into ustar prefix (155) + name (100) on a '/'.
+  let fileName = name
+  let filePrefix = ''
+  if (fileName.length > 100) {
+    const cut = fileName.lastIndexOf('/', 155)
+    if (cut <= 0) throw new Error(`tar: path too long and unsplittable: ${name}`)
+    filePrefix = fileName.slice(0, cut)
+    fileName = fileName.slice(cut + 1)
+    if (fileName.length > 100 || filePrefix.length > 155) {
+      throw new Error(`tar: path too long: ${name}`)
+    }
+  }
+
+  header.set(enc.encode(fileName), 0)                 // name
+  header.set(octal(0o644, 8), 100)                    // mode
+  header.set(octal(0, 8), 108)                        // uid
+  header.set(octal(0, 8), 116)                        // gid
+  header.set(octal(size, 12), 124)                    // size
+  header.set(octal(mtime, 12), 136)                   // mtime
+  header.set(enc.encode('        '), 148)             // checksum placeholder (spaces)
+  header[156] = 0x30                                  // typeflag '0' regular file
+  header.set(enc.encode('ustar\0'), 257)              // magic
+  header.set(enc.encode('00'), 263)                   // version
+  header.set(enc.encode(filePrefix), 345)             // prefix
+
+  let checksum = 0
+  for (const byte of header) checksum += byte
+  const cs = checksum.toString(8).padStart(6, '0') + '\0 '
+  header.set(enc.encode(cs), 148)
+  return header
+}
+
+/** One .tar.gz of the whole sealed bundle. `excludePrefix` leaves keys out
+ *  (R-T5: media bytes skip the wire when they travel by presigned URL). */
+export async function tarGzBundle(
+  storage: StorageAdapter,
+  bundleId: string,
+  opts: { mtime?: number; excludePrefix?: string } = {},
+): Promise<Uint8Array> {
+  const mtime = opts.mtime ?? 0
+  const keys = (await bundleKeys(storage, bundleId))
+    .filter((k) => !opts.excludePrefix || !k.startsWith(opts.excludePrefix))
+  const chunks: Uint8Array[] = []
+
+  for (const key of keys) {
+    const bytes = await storage.read(`${prefix(bundleId)}/${key}`)
+    if (!bytes) throw new Error(`bundle ${bundleId} is missing "${key}" - refusing to package an incomplete archive`)
+    chunks.push(tarHeader(key, bytes.byteLength, mtime))
+    chunks.push(bytes)
+    const pad = (512 - (bytes.byteLength % 512)) % 512
+    if (pad > 0) chunks.push(new Uint8Array(pad))
+  }
+  chunks.push(new Uint8Array(1024))   // end-of-archive: two zero blocks
+
+  const total = chunks.reduce((n, c) => n + c.byteLength, 0)
+  const tar = new Uint8Array(total)
+  let offset = 0
+  for (const c of chunks) { tar.set(c, offset); offset += c.byteLength }
+
+  return new Uint8Array(gzipSync(tar))
+}
+
+// ── reading (I-T5: uploads) ──────────────────────────────────────────────────
+
+export interface TarEntry { path: string; bytes: Uint8Array }
+
+/** Extracts regular files from a .tar.gz (ustar incl. prefix field). */
+export function untarGz(archive: Uint8Array): TarEntry[] {
+  const tar = new Uint8Array(gunzipSync(archive))
+  const dec = new TextDecoder()
+  const entries: TarEntry[] = []
+  let offset = 0
+  while (offset + 512 <= tar.byteLength) {
+    const block = tar.subarray(offset, offset + 512)
+    if (block.every((b) => b === 0)) break   // end-of-archive
+    const name = dec.decode(block.subarray(0, 100)).replace(/\0.*$/, '')
+    const prefixField = dec.decode(block.subarray(345, 500)).replace(/\0.*$/, '')
+    const size = parseInt(dec.decode(block.subarray(124, 136)).replace(/\0.*$/, '').trim() || '0', 8)
+    const typeflag = block[156]
+    offset += 512
+    const path = prefixField ? `${prefixField}/${name}` : name
+    if (typeflag === 0x30 || typeflag === 0) {
+      entries.push({ path, bytes: tar.slice(offset, offset + size) })
+    }
+    offset += Math.ceil(size / 512) * 512
+  }
+  return entries
+}
+
+/**
+ * Writes an uploaded .tar.gz into storage as a bundle under `bundleId`.
+ * Refuses archives without a manifest (they were never sealed) and entries
+ * that escape the bundle prefix.
+ */
+export async function importBundleFromTarGz(
+  storage: StorageAdapter,
+  bundleId: string,
+  archive: Uint8Array,
+): Promise<string> {
+  const entries = untarGz(archive)
+  if (!entries.some((e) => e.path === 'manifest.json')) {
+    throw new Error('archive has no manifest.json - not a sealed Tangen export')
+  }
+  for (const entry of entries) {
+    if (entry.path.includes('..') || entry.path.startsWith('/')) {
+      throw new Error(`archive entry escapes the bundle: ${entry.path}`)
+    }
+    await storage.write(`${prefix(bundleId)}/${entry.path}`, entry.bytes)
+  }
+  return bundleId
+}