was-teaching-server 0.9.1 → 0.10.0

package/dist/backends/postgres.js

@@ -30,14 +30,15 @@ import * as tar from 'tar-stream';
 import YAML from 'yaml';
 import { StorageError, ResourceNotFoundError, SpaceNotFoundError, QuotaExceededError, CountQuotaExceededError, PayloadTooLargeError, PreconditionFailedError, KeystoreStateConflictError, KeyIdConflictError, DuplicateRevocationError } from '../errors.js';
 import { applyMigrations } from './postgresSchema.js';
-import { extractTarEntries, buildImportPlan } from '../lib/importTar.js';
+import { extractTarEntries, buildImportPlan, metaSidecarFileId } from '../lib/importTar.js';
 import { collectionPath, resourcePath } from '../lib/paths.js';
-import { fileNameFor, parseResourceFileName } from '../lib/resourceFileName.js';
+import { fileNameFor, parseResourceFileName, chunkDirName, parseChunkDirName, parseChunkIndexSegment } from '../lib/resourceFileName.js';
+import { assertValidId } from '../lib/validateId.js';
 import { sanitizeBackendRecord } from '../lib/backends.js';
 import { backendUsageFields } from '../lib/backendUsage.js';
 import { assertEncryptedWriteConforms } from '../lib/encryption.js';
 import { encodeCursor, decodeCursor } from '../lib/cursor.js';
-import { buildExportManifest } from '../lib/exportManifest.js';
+import { buildExportManifest, EXPORT_ENTRY_MTIME } from '../lib/exportManifest.js';
 import { revocationFileName } from '../lib/revocations.js';
 import { isJson } from '../lib/isJson.js';
 import { normalizeDescriptionWrite } from '../lib/collectionDescription.js';
@@ -277,11 +278,14 @@ export class PostgresBackend {
             // `key-epochs`: multi-recipient encrypted Collections -- per-epoch wrapped
             // keys on the `encryption` marker, a client-declared `epoch` stamp on
             // Resources, and conditional (`If-Match`) Collection Description writes.
+            // `chunked-streams`: chunk addressing at `/{resourceId}/chunks/{n}`, opaque
+            // per-chunk raw-bytes storage in the `chunks` table.
             features: [
                 'conditional-writes',
                 'changes-query',
                 'blinded-index-query',
-                'key-epochs'
+                'key-epochs',
+                'chunked-streams'
             ]
         };
     }
@@ -340,6 +344,30 @@ export class PostgresBackend {
             });
         }
     }
+    /**
+     * Serializes concurrent CREATORS of one not-yet-existing row (a Resource or
+     * a chunk) on a transaction-scoped advisory lock keyed by the row's
+     * identity. Under READ COMMITTED a `SELECT ... FOR UPDATE` on an absent row
+     * locks nothing (no gap locks), so two concurrent creators would both read
+     * "no prior row" and both apply their full byte size as the usage delta --
+     * and while the `ON CONFLICT` arm recomputes `version` from the conflicting
+     * row, it cannot retroactively fix the loser's delta, leaving `usage_bytes`
+     * inflated by one write's size. The caller takes this lock when its
+     * lock-nothing SELECT found no row, then RE-reads the row: the second
+     * creator blocks here until the first commits, and its re-read sees the
+     * committed row, so its precondition, version, and usage delta are computed
+     * from accurate state. Held to commit (advisory xact lock). The `create:`
+     * prefix keeps this key domain distinct from the unique-blinded-term
+     * advisory lock, which hashes the bare `(spaceId, collectionId)`.
+     * @param options {object}
+     * @param options.client {pg.PoolClient}
+     * @param options.spaceId {string}
+     * @param options.rowKey {string}   the row's identity within the Space
+     * @returns {Promise<void>}
+     */
+    async _lockSameKeyCreate({ client, spaceId, rowKey }) {
+        await client.query('SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))', [spaceId, `create:${rowKey}`]);
+    }
     // Quotas
     /**
      * Reports the Space's usage from the transactional counter (no measurement
@@ -356,9 +384,16 @@ export class PostgresBackend {
         const usageBytes = rows[0] ? Number(rows[0].usage_bytes) : 0;
         let usageByCollection;
         if (includeCollections) {
-            const { rows: collectionRows } = await this._pool.query(`SELECT collection_id, COALESCE(SUM(size_bytes), 0) AS usage
-           FROM resources
-          WHERE space_id = $1
+            // Per-Collection usage sums both Resource content bytes and chunk bytes
+            // (the `chunked-streams` feature) so the breakdown agrees with the
+            // Space total in the transactional counter.
+            const { rows: collectionRows } = await this._pool.query(`SELECT collection_id, COALESCE(SUM(bytes), 0) AS usage FROM (
+           SELECT collection_id, size_bytes AS bytes FROM resources
+             WHERE space_id = $1
+           UNION ALL
+           SELECT collection_id, size AS bytes FROM chunks
+             WHERE space_id = $1
+         ) usage_rows
           GROUP BY collection_id
           ORDER BY collection_id`, [spaceId]);
             usageByCollection = collectionRows.map(row => ({
@@ -387,6 +422,8 @@ export class PostgresBackend {
          (SELECT COALESCE(usage_bytes, 0) FROM spaces WHERE space_id = $1)
            AS space_total,
          (SELECT COALESCE(SUM(size_bytes), 0) FROM resources
+           WHERE space_id = $1 AND collection_id = $2)
+         + (SELECT COALESCE(SUM(size), 0) FROM chunks
            WHERE space_id = $1 AND collection_id = $2) AS collection_total`, [spaceId, collectionId]);
         const spaceTotalBytes = Number(rows[0]?.space_total ?? 0);
         const usageBytes = Number(rows[0]?.collection_total ?? 0);
@@ -698,8 +735,14 @@ export class PostgresBackend {
      */
     async deleteCollection({ spaceId, collectionId }) {
         await this._withTransaction(async (client) => {
-            const { rows } = await client.query(`SELECT COALESCE(SUM(size_bytes), 0) AS total FROM resources
-          WHERE space_id = $1 AND collection_id = $2`, [spaceId, collectionId]);
+            // The Collection's freed bytes are its Resource content plus its chunk
+            // bytes (the `chunked-streams` feature); both cascade away with the
+            // Collection row, so both leave the quota counter.
+            const { rows } = await client.query(`SELECT
+           (SELECT COALESCE(SUM(size_bytes), 0) FROM resources
+             WHERE space_id = $1 AND collection_id = $2)
+         + (SELECT COALESCE(SUM(size), 0) FROM chunks
+             WHERE space_id = $1 AND collection_id = $2) AS total`, [spaceId, collectionId]);
             const freedBytes = Number(rows[0]?.total ?? 0);
             await client.query(`DELETE FROM collections WHERE space_id = $1 AND collection_id = $2`, [spaceId, collectionId]);
             // Collection- and Resource-level policies live under the Collection (the
@@ -887,7 +930,23 @@ export class PostgresBackend {
            FROM resources
           WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
           FOR UPDATE`, [spaceId, collectionId, resourceId]);
-            const prior = rows[0];
+            let prior = rows[0];
+            if (prior === undefined) {
+                // The lock-nothing case: serialize with any concurrent creator of the
+                // same id and re-read, so `exists` / `priorSize` below reflect the row
+                // it committed (see `_lockSameKeyCreate` -- without this, both
+                // creators would count their full byte size as the usage delta).
+                await this._lockSameKeyCreate({
+                    client,
+                    spaceId,
+                    rowKey: `${collectionId}/${resourceId}`
+                });
+                const { rows: reread } = await client.query(`SELECT version, size_bytes, deleted, created_at, created_by
+             FROM resources
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+            FOR UPDATE`, [spaceId, collectionId, resourceId]);
+                prior = reread[0];
+            }
             const exists = prior !== undefined && !prior.deleted;
             if (ifMatch !== undefined || ifNoneMatch) {
                 assertWritePrecondition({
@@ -914,7 +973,7 @@ export class PostgresBackend {
             }
             const now = new Date().toISOString();
             const version = (prior?.version ?? 0) + 1;
-            const priorSize = exists ? Number(prior.size_bytes) : 0;
+            const priorSize = exists ? Number(prior?.size_bytes ?? 0) : 0;
             const delta = content.length - priorSize;
             if (delta !== 0) {
                 await this._applyUsageDelta({ client, spaceId, delta });
@@ -924,10 +983,11 @@ export class PostgresBackend {
             // dropped both (the metadata went with the deleted Resource).
             //
             // Create-if-absent atomicity: when `If-None-Match: *` found NO prior row
-            // (a tombstone is a real row and stays lock-serialized), the SELECT FOR
-            // UPDATE locked nothing -- READ COMMITTED has no gap locks -- so a
-            // concurrent creator may have raced past the same precondition. A plain
-            // INSERT (no ON CONFLICT) makes the primary key the arbiter: the loser's
+            // (a tombstone is a real row and stays lock-serialized), concurrent
+            // creators through this method are already serialized by
+            // `_lockSameKeyCreate` above -- but a writer that does not take that
+            // lock (`importSpace`'s plain INSERTs) can still race. A plain INSERT
+            // (no ON CONFLICT) keeps the primary key as the arbiter: the loser's
             // unique violation maps to the 412 the precondition would have thrown.
             // `createdBy` names the Resource's creator, not its last writer: taken
             // from this write's invoker only when there is no prior row at all
@@ -1062,7 +1122,19 @@ export class PostgresBackend {
                 // no-op, keeping an existing tombstone's change-feed entry stable.
                 return;
             }
-            const freedBytes = Number(prior.size_bytes);
+            // A soft delete is an UPDATE, not a row removal, so the chunk foreign
+            // key's ON DELETE CASCADE does not fire -- remove the Resource's chunks
+            // (the `chunked-streams` feature) explicitly in this same transaction so
+            // they never outlive their parent, and return their bytes to the quota
+            // counter alongside the Resource's content bytes.
+            const { rows: chunkRows } = await client.query(`SELECT COALESCE(SUM(size), 0) AS total FROM chunks
+          WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3`, [spaceId, collectionId, resourceId]);
+            const freedChunkBytes = Number(chunkRows[0]?.total ?? 0);
+            if (freedChunkBytes > 0) {
+                await client.query(`DELETE FROM chunks
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3`, [spaceId, collectionId, resourceId]);
+            }
+            const freedBytes = Number(prior.size_bytes) + freedChunkBytes;
             if (freedBytes > 0) {
                 await this._applyUsageDelta({ client, spaceId, delta: -freedBytes });
             }
@@ -1168,6 +1240,276 @@ export class PostgresBackend {
             return { metaVersion };
         });
     }
+    // Chunks (the `chunked-streams` feature)
+    /**
+     * Writes one chunk of a chunked Resource as one transaction: the parent
+     * Resource must exist (checked atomically -- a `FOR SHARE` lock on it also
+     * blocks a concurrent delete of the parent for the duration of the write, so
+     * a chunk can never be orphaned by a racing `deleteResource`), the chunk row
+     * is locked, its precondition evaluated, its monotonic `version` bumped, and
+     * the transactional quota delta applied. The chunk body is stored opaquely as
+     * a single `bytea`, the buffered-blob path (bounded by `maxUploadBytes`),
+     * exactly like a binary Resource representation.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.chunkIndex {number}   a non-negative safe integer
+     * @param options.input {ResourceInput}
+     * @param [options.ifMatch] {string}
+     * @param [options.ifNoneMatch] {boolean}
+     * @returns {Promise<{ version: number }>}   the chunk's new version
+     */
+    async writeChunk({ spaceId, collectionId, resourceId, chunkIndex, input, ifMatch, ifNoneMatch }) {
+        const { maxUploadBytes } = this;
+        let bytes;
+        if (input.kind === 'json') {
+            bytes = Buffer.from(JSON.stringify(input.data));
+            if (bytes.length > maxUploadBytes) {
+                throw new PayloadTooLargeError({
+                    maxUploadBytes,
+                    backendId: this.describe().id,
+                    uploadBytes: bytes.length
+                });
+            }
+        }
+        else {
+            // Pre-flight a declared size, then buffer through the counting guard that
+            // hard-caps a body whose size is omitted or understated. Buffering
+            // happens BEFORE the transaction so a slow upload holds no row lock.
+            if (input.declaredBytes !== undefined &&
+                input.declaredBytes > maxUploadBytes) {
+                throw new PayloadTooLargeError({
+                    maxUploadBytes,
+                    backendId: this.describe().id,
+                    uploadBytes: input.declaredBytes
+                });
+            }
+            bytes = await bufferStreamCapped({
+                stream: input.stream,
+                maxUploadBytes,
+                backendId: this.describe().id
+            });
+        }
+        return this._withTransaction(async (client) => {
+            // Parent Resource must exist (and not be a tombstone). `FOR SHARE`
+            // conflicts with the `FOR UPDATE` a concurrent `deleteResource` takes, so
+            // the two serialize on the parent row -- the parent cannot be deleted
+            // between this check and the chunk write.
+            const { rows: parentRows } = await client.query(`SELECT deleted FROM resources
+          WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+          FOR SHARE`, [spaceId, collectionId, resourceId]);
+            const parent = parentRows[0];
+            if (!parent || parent.deleted) {
+                throw new ResourceNotFoundError({ requestName: 'Write Chunk' });
+            }
+            // Lock the chunk row (if any) and read its current version/size, so the
+            // precondition, the monotonic bump, and the usage delta are all atomic
+            // with the write.
+            const { rows } = await client.query(`SELECT version, size FROM chunks
+          WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+            AND chunk_index = $4
+          FOR UPDATE`, [spaceId, collectionId, resourceId, chunkIndex]);
+            let prior = rows[0];
+            const chunkLabel = `${resourceId}/chunks/${chunkIndex}`;
+            if (prior === undefined) {
+                // The lock-nothing case: serialize with any concurrent creator of the
+                // same chunk and re-read, so the usage delta below reflects the row it
+                // committed (see `_lockSameKeyCreate`).
+                await this._lockSameKeyCreate({
+                    client,
+                    spaceId,
+                    rowKey: `${collectionId}/${chunkLabel}`
+                });
+                const { rows: reread } = await client.query(`SELECT version, size FROM chunks
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+              AND chunk_index = $4
+            FOR UPDATE`, [spaceId, collectionId, resourceId, chunkIndex]);
+                prior = reread[0];
+            }
+            const exists = prior !== undefined;
+            if (ifMatch !== undefined || ifNoneMatch) {
+                assertWritePrecondition({
+                    resourceId: chunkLabel,
+                    exists,
+                    currentVersion: prior?.version ?? 0,
+                    ifMatch,
+                    ifNoneMatch
+                });
+            }
+            const version = (prior?.version ?? 0) + 1;
+            const priorSize = exists ? Number(prior?.size ?? 0) : 0;
+            const delta = bytes.length - priorSize;
+            if (delta !== 0) {
+                await this._applyUsageDelta({ client, spaceId, delta });
+            }
+            const values = [
+                spaceId,
+                collectionId,
+                resourceId,
+                chunkIndex,
+                input.contentType,
+                bytes,
+                bytes.length,
+                version
+            ];
+            const insertSql = `
+        INSERT INTO chunks (
+          space_id, collection_id, resource_id, chunk_index,
+          content_type, bytes, size, version
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`;
+            // Create-if-absent atomicity mirrors `writeResource`: concurrent
+            // creators through this method are serialized by `_lockSameKeyCreate`
+            // above, and against a writer that does not take that lock
+            // (`importSpace`'s plain INSERTs) the plain INSERT keeps the primary key
+            // as the arbiter -- a racing creator's unique violation maps to the 412
+            // the precondition would have thrown.
+            if (ifNoneMatch && prior === undefined) {
+                try {
+                    await client.query(insertSql, values);
+                }
+                catch (err) {
+                    if (err.code === '23505') {
+                        throw new PreconditionFailedError({
+                            detail: `Chunk '${chunkLabel}' already exists (If-None-Match: *).`
+                        });
+                    }
+                    throw err;
+                }
+                return { version };
+            }
+            // The conflict update derives `version` from the row (`chunks.version +
+            // 1`), not from the pre-read, so a concurrent creator that slipped in
+            // after our lock-nothing SELECT still advances the counter monotonically.
+            // RETURNING reports the version that actually landed.
+            const { rows: written } = await client.query(`${insertSql}
+         ON CONFLICT (space_id, collection_id, resource_id, chunk_index)
+         DO UPDATE SET
+           content_type = EXCLUDED.content_type,
+           bytes = EXCLUDED.bytes,
+           size = EXCLUDED.size,
+           version = chunks.version + 1
+         RETURNING version`, values);
+            return { version: written[0].version };
+        });
+    }
+    /**
+     * Reads a chunk's bytes. Rejects with `ResourceNotFoundError` (404) when no
+     * chunk is stored at that index.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.chunkIndex {number}
+     * @returns {Promise<ResourceResult>}
+     */
+    async getChunk({ spaceId, collectionId, resourceId, chunkIndex }) {
+        const { rows } = await this._pool.query(`SELECT content_type, bytes, version FROM chunks
+        WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+          AND chunk_index = $4`, [spaceId, collectionId, resourceId, chunkIndex]);
+        const row = rows[0];
+        if (!row) {
+            throw new ResourceNotFoundError({ requestName: 'Get Chunk' });
+        }
+        return {
+            resourceStream: Readable.from(row.bytes),
+            storedResourceType: row.content_type,
+            version: row.version
+        };
+    }
+    /**
+     * Reads a chunk's stored content-type / size / version (the HEAD payload
+     * headers). Resolves `undefined` when the chunk is absent.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.chunkIndex {number}
+     * @returns {Promise<{ contentType: string, size: number, version?: number }
+     *   | undefined>}
+     */
+    async getChunkMetadata({ spaceId, collectionId, resourceId, chunkIndex }) {
+        const { rows } = await this._pool.query(`SELECT content_type, size, version FROM chunks
+        WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+          AND chunk_index = $4`, [spaceId, collectionId, resourceId, chunkIndex]);
+        const row = rows[0];
+        if (!row) {
+            return undefined;
+        }
+        return {
+            contentType: row.content_type,
+            size: Number(row.size),
+            version: row.version
+        };
+    }
+    /**
+     * Deletes one chunk as one transaction (the chunk row is locked, its
+     * `ifMatch` precondition evaluated atomically, and its bytes returned to the
+     * quota counter). Resolves `true` when a chunk was removed, `false` when none
+     * was stored at that index (the handler 404s on `false` -- chunk deletes are
+     * not silently idempotent, unlike `deleteResource`).
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.chunkIndex {number}
+     * @param [options.ifMatch] {string}
+     * @returns {Promise<boolean>}
+     */
+    async deleteChunk({ spaceId, collectionId, resourceId, chunkIndex, ifMatch }) {
+        return this._withTransaction(async (client) => {
+            const { rows } = await client.query(`SELECT version, size FROM chunks
+          WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+            AND chunk_index = $4
+          FOR UPDATE`, [spaceId, collectionId, resourceId, chunkIndex]);
+            const prior = rows[0];
+            if (prior === undefined) {
+                return false;
+            }
+            if (ifMatch !== undefined) {
+                assertWritePrecondition({
+                    resourceId: `${resourceId}/chunks/${chunkIndex}`,
+                    exists: true,
+                    currentVersion: prior.version,
+                    ifMatch
+                });
+            }
+            await client.query(`DELETE FROM chunks
+          WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+            AND chunk_index = $4`, [spaceId, collectionId, resourceId, chunkIndex]);
+            const freedBytes = Number(prior.size);
+            if (freedBytes > 0) {
+                await this._applyUsageDelta({ client, spaceId, delta: -freedBytes });
+            }
+            return true;
+        });
+    }
+    /**
+     * Lists a Resource's stored chunks in ascending `chunk_index` order -- the
+     * discovery/reassembly listing. The opaque `bytes` column is deliberately not
+     * selected. An empty listing (Resource with no chunks, or an absent Resource)
+     * resolves `{ count: 0, chunks: [] }`.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @returns {Promise<{ count: number, chunks: Array<{ index: number, size:
+     *   number, contentType: string, version?: number }> }>}
+     */
+    async listChunks({ spaceId, collectionId, resourceId }) {
+        const { rows } = await this._pool.query(`SELECT chunk_index, size, content_type, version FROM chunks
+        WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+        ORDER BY chunk_index`, [spaceId, collectionId, resourceId]);
+        return {
+            count: rows.length,
+            chunks: rows.map(row => ({
+                index: row.chunk_index,
+                size: Number(row.size),
+                contentType: row.content_type,
+                version: row.version
+            }))
+        };
+    }
     /**
      * Replication change feed (the `changes` query profile): one indexed keyset
      * query over `(updatedAt, resourceId)`, tombstones included, JSON documents
@@ -1678,7 +2020,7 @@ export class PostgresBackend {
         if (!spaceDescription) {
             throw new SpaceNotFoundError({ requestName: 'Export Space' });
         }
-        const [{ rows: policyRows }, { rows: collectionRows }, { rows: resourceRows }, { rows: revocationRows }] = await Promise.all([
+        const [{ rows: policyRows }, { rows: collectionRows }, { rows: resourceRows }, { rows: revocationRows }, { rows: chunkRows }] = await Promise.all([
             this._pool.query(`SELECT collection_id, resource_id, policy FROM policies
             WHERE space_id = $1`, [spaceId]),
             this._pool.query(`SELECT collection_id, description, description_version FROM collections
@@ -1690,7 +2032,12 @@ export class PostgresBackend {
                 created_at, updated_at, created_by
            FROM resources WHERE space_id = $1`, [spaceId]),
             this._pool.query(`SELECT delegator, capability_id, record FROM space_revocations
-            WHERE space_id = $1`, [spaceId])
+            WHERE space_id = $1`, [spaceId]),
+            // Chunk metadata only -- bytes are fetched one chunk at a time while
+            // packing, so an export never holds a chunked Resource whole in memory.
+            this._pool.query(`SELECT collection_id, resource_id, chunk_index, content_type, version
+           FROM chunks WHERE space_id = $1
+          ORDER BY collection_id, resource_id, chunk_index`, [spaceId])
         ]);
         // Assemble the per-entry file lists in the filesystem's shapes: files are
         // named by the shared codecs and sorted with localeCompare, matching the
@@ -1765,6 +2112,46 @@ export class PostgresBackend {
                 });
             }
         }
+        // Chunks (the `chunked-streams` feature): each chunked Resource contributes
+        // one `.chunks.<encResourceId>/` subdirectory in its Collection dir, in the
+        // exact filesystem-backend layout so an archive imports into either backend.
+        // A chunk is stored there as a Resource keyed by its stringified index: an
+        // `r.<index>.<encContentType>.<ext>` representation file (`fileNameFor`)
+        // plus a `.meta.<index>.json` version sidecar. Files within a chunk dir are
+        // sorted by name (the filesystem's readdir sort). Rows arrive ordered by
+        // `(collection, resource, index)`.
+        const chunkDirsByResource = new Map();
+        for (const row of chunkRows) {
+            const dirKey = `${row.collection_id}/${row.resource_id}`;
+            let chunkFiles = chunkDirsByResource.get(dirKey);
+            if (!chunkFiles) {
+                chunkFiles = [];
+                chunkDirsByResource.set(dirKey, chunkFiles);
+                filesFor(row.collection_id).push({
+                    name: chunkDirName(row.resource_id),
+                    chunkDir: chunkFiles
+                });
+            }
+            const chunkId = String(row.chunk_index);
+            chunkFiles.push({
+                name: fileNameFor({
+                    resourceId: chunkId,
+                    contentType: row.content_type
+                }),
+                chunk: {
+                    collectionId: row.collection_id,
+                    resourceId: row.resource_id,
+                    chunkIndex: row.chunk_index
+                }
+            });
+            chunkFiles.push({
+                name: `.meta.${chunkId}.json`,
+                bytes: Buffer.from(JSON.stringify({ version: row.version }))
+            });
+        }
+        for (const chunkFiles of chunkDirsByResource.values()) {
+            chunkFiles.sort((left, right) => left.name.localeCompare(right.name));
+        }
         // Top-level order: space-level files and collection dirs interleaved,
         // sorted by name -- the same order the filesystem's readdir+sort yields.
         const topLevel = [
@@ -1791,33 +2178,59 @@ export class PostgresBackend {
         const manifest = buildExportManifest({
             spaceId,
             entries: topLevel.map(entry => entry.kind === 'collection'
-                ? { name: entry.name, files: entry.files.map(file => file.name) }
+                ? {
+                    name: entry.name,
+                    // A chunk directory expands to its `.chunks.<encId>/<file>`
+                    // relative paths (mirroring the pack order), so the manifest
+                    // matches the filesystem backend's for the same Space.
+                    files: entry.files.flatMap(file => 'chunkDir' in file
+                        ? file.chunkDir.map(child => `${file.name}/${child.name}`)
+                        : [file.name])
+                }
                 : { name: entry.name }),
             revocationFiles: revocationFiles.map(file => file.name)
         });
+        // Fixed mtime on every entry so the archive is byte-reproducible (see
+        // EXPORT_ENTRY_MTIME).
+        const mtime = EXPORT_ENTRY_MTIME;
         const pack = tar.pack();
-        pack.entry({ name: 'manifest.yml' }, YAML.stringify(manifest));
-        pack.entry({ name: 'space/', type: 'directory' });
-        pack.entry({ name: `space/${spaceId}/`, type: 'directory' });
+        pack.entry({ name: 'manifest.yml', mtime }, YAML.stringify(manifest));
+        pack.entry({ name: 'space/', type: 'directory', mtime });
+        pack.entry({ name: `space/${spaceId}/`, type: 'directory', mtime });
         for (const entry of topLevel) {
             const entryTarget = `space/${spaceId}/${entry.name}`;
             if (entry.kind === 'collection') {
-                pack.entry({ name: `${entryTarget}/`, type: 'directory' });
+                pack.entry({ name: `${entryTarget}/`, type: 'directory', mtime });
                 for (const file of entry.files) {
+                    if ('chunkDir' in file) {
+                        // A chunked Resource's `.chunks.<encId>/` subdirectory: emit the
+                        // directory entry, then each file -- an inline `.meta.<index>.json`
+                        // sidecar, or a chunk representation whose bytes are fetched one at
+                        // a time.
+                        const dirTarget = `${entryTarget}/${file.name}`;
+                        pack.entry({ name: `${dirTarget}/`, type: 'directory', mtime });
+                        for (const chunkFile of file.chunkDir) {
+                            const bytes = 'bytes' in chunkFile
+                                ? chunkFile.bytes
+                                : await this._chunkContent({ spaceId, ...chunkFile.chunk });
+                            pack.entry({ name: `${dirTarget}/${chunkFile.name}`, mtime }, bytes);
+                        }
+                        continue;
+                    }
                     const bytes = 'bytes' in file
                         ? file.bytes
                         : await this._resourceContent({ spaceId, ...file.resource });
-                    pack.entry({ name: `${entryTarget}/${file.name}` }, bytes);
+                    pack.entry({ name: `${entryTarget}/${file.name}`, mtime }, bytes);
                 }
             }
             else {
-                pack.entry({ name: entryTarget }, entry.bytes);
+                pack.entry({ name: entryTarget, mtime }, entry.bytes);
             }
         }
         if (revocationFiles.length > 0) {
-            pack.entry({ name: 'revocations/', type: 'directory' });
+            pack.entry({ name: 'revocations/', type: 'directory', mtime });
             for (const file of revocationFiles) {
-                pack.entry({ name: `revocations/${file.name}` }, file.bytes);
+                pack.entry({ name: `revocations/${file.name}`, mtime }, file.bytes);
             }
         }
         pack.finalize();
@@ -1839,6 +2252,24 @@ export class PostgresBackend {
         WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3`, [spaceId, collectionId, resourceId]);
         return rows[0]?.content ?? Buffer.alloc(0);
     }
+    /**
+     * Fetches one chunk's bytes for the export pack loop (the `chunked-streams`
+     * feature). A chunk removed between the metadata pass and this read yields an
+     * empty body rather than failing the whole archive, matching
+     * `_resourceContent`.
+     * @param options {object}
+     * @param options.spaceId {string}
+     * @param options.collectionId {string}
+     * @param options.resourceId {string}
+     * @param options.chunkIndex {number}
+     * @returns {Promise<Buffer>}
+     */
+    async _chunkContent({ spaceId, collectionId, resourceId, chunkIndex }) {
+        const { rows } = await this._pool.query(`SELECT bytes FROM chunks
+        WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+          AND chunk_index = $4`, [spaceId, collectionId, resourceId, chunkIndex]);
+        return rows[0]?.bytes ?? Buffer.alloc(0);
+    }
     /**
      * Merges a WAS space-export tarball into an existing Space with the same
      * three-invariant pre-flight (per-entry 413, fail-closed 422 encryption
@@ -1855,6 +2286,10 @@ export class PostgresBackend {
     async importSpace({ spaceId, tarStream }) {
         const entries = await extractTarEntries(tarStream);
         const { spacePolicy, collections, revocations } = buildImportPlan(entries);
+        // Chunk entries (the `chunked-streams` feature) live in per-Resource
+        // `.chunks.<encId>/` subdirectories, which `buildImportPlan` skips (it
+        // ignores nested files); parse them straight off the raw tar entries.
+        const chunkEntries = this._chunkEntriesFromArchive(entries);
         const { capacityBytes, maxUploadBytes, maxCollectionsPerSpace, maxResourcesPerSpace } = this;
         return this._withTransaction(async (client) => {
             await this._ensureSpaceRow({ client, spaceId });
@@ -1918,6 +2353,19 @@ export class PostgresBackend {
                     incomingBytes += body.length;
                 }
             }
+            // Chunks (the `chunked-streams` feature) are opaque bytes -- no
+            // encryption-conformance check applies -- but they count the same per-body
+            // 413 and the (conservative) capacity pre-flight as Resource bodies.
+            for (const chunk of chunkEntries) {
+                if (chunk.body.length > maxUploadBytes) {
+                    throw new PayloadTooLargeError({
+                        maxUploadBytes,
+                        backendId: this.describe().id,
+                        uploadBytes: chunk.body.length
+                    });
+                }
+                incomingBytes += chunk.body.length;
+            }
             if (capacityBytes !== undefined &&
                 currentUsage + incomingBytes > capacityBytes) {
                 throw new QuotaExceededError({ spaceId, capacityBytes });
@@ -2081,13 +2529,53 @@ export class PostgresBackend {
                     stats.resourcesCreated++;
                 }
             }
-            if (createdBytes > 0) {
+            // Chunks (the `chunked-streams` feature): restore each archived chunk
+            // skip-not-overwrite, after the Resource apply loop so a chunk's parent
+            // Resource row already exists in this transaction (the foreign key
+            // requires it). An orphan chunk -- one whose parent is absent or a
+            // tombstone -- is skipped rather than resurrected. Existing chunk rows are
+            // left untouched.
+            let createdChunkBytes = 0;
+            for (const chunk of chunkEntries) {
+                const { rows: parentRows } = await client.query(`SELECT deleted FROM resources
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3`, [spaceId, chunk.collectionId, chunk.resourceId]);
+                const parent = parentRows[0];
+                if (!parent || parent.deleted) {
+                    continue;
+                }
+                const { rows: existingChunkRows } = await client.query(`SELECT 1 FROM chunks
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+              AND chunk_index = $4`, [spaceId, chunk.collectionId, chunk.resourceId, chunk.chunkIndex]);
+                if (existingChunkRows.length > 0) {
+                    continue;
+                }
+                // The chunk's `version` comes from its archived `.meta.<index>.json`
+                // sidecar; an archive without one (or a chunk written before sidecars)
+                // starts at version 1, the same fresh-write default as a Resource
+                // restored without a sidecar.
+                await client.query(`INSERT INTO chunks (
+             space_id, collection_id, resource_id, chunk_index,
+             content_type, bytes, size, version
+           ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                    spaceId,
+                    chunk.collectionId,
+                    chunk.resourceId,
+                    chunk.chunkIndex,
+                    chunk.contentType,
+                    chunk.body,
+                    chunk.body.length,
+                    chunk.version ?? 1
+                ]);
+                createdChunkBytes += chunk.body.length;
+            }
+            const createdTotalBytes = createdBytes + createdChunkBytes;
+            if (createdTotalBytes > 0) {
                 // The pre-flight was conservative (it counted skips too), so the
                 // actual created total always fits; apply it unguarded.
                 await this._applyUsageDelta({
                     client,
                     spaceId,
-                    delta: createdBytes
+                    delta: createdTotalBytes
                 });
             }
             // Restore the archive's Space-scoped zcap revocations under this
@@ -2160,5 +2648,113 @@ export class PostgresBackend {
             sidecar?.epoch ?? null
         ]);
     }
+    /**
+     * Parses a Space-export archive's chunk entries (the `chunked-streams`
+     * feature) out of the raw tar entry map, in the filesystem backend's on-disk
+     * layout so archives round-trip between the two backends. Chunk files live at
+     * `space/<sourceSpaceId>/<collectionId>/.chunks.<encResourceId>/<file>` --
+     * where a chunk is a Resource keyed by its stringified index: an
+     * `r.<index>.<encContentType>.<ext>` representation paired with an optional
+     * `.meta.<index>.json` version sidecar. `buildImportPlan` skips these (it
+     * ignores nested Collection-dir files), so they are parsed here. Ids parsed
+     * from the archive are validated (the path-traversal guard); a file whose
+     * raw index segment is not canonical (`parseChunkIndexSegment`) is ignored,
+     * and a sidecar with no paired representation is dropped (a chunk keeps no
+     * tombstone).
+     * @param entries {Map<string, TarEntry>}
+     * @returns {Array<{ collectionId: string, resourceId: string, chunkIndex:
+     *   number, contentType: string, body: Buffer, version?: number }>}
+     */
+    _chunkEntriesFromArchive(entries) {
+        // Accumulate the representation and the sidecar of each chunk under one
+        // key, then emit only the chunks that carry a representation.
+        const staged = new Map();
+        const pattern = /^space\/[^/]+\/([^/]+)\/(\.chunks\.[^/]+)\/([^/]+)$/;
+        for (const [entryName, entry] of entries) {
+            if (entry.type !== 'file' || !entry.body) {
+                continue;
+            }
+            const match = entryName.match(pattern);
+            if (!match) {
+                continue;
+            }
+            const collectionId = match[1];
+            const resourceId = parseChunkDirName(match[2]);
+            const fileName = match[3];
+            if (resourceId === undefined) {
+                continue;
+            }
+            // Reject a path-traversal / non-URL-safe id parsed from the archive
+            // before it keys a destination row.
+            assertValidId(collectionId, {
+                kind: 'collection',
+                requestName: 'Import Space'
+            });
+            assertValidId(resourceId, {
+                kind: 'resource',
+                requestName: 'Import Space'
+            });
+            // A chunk's index is the "resource id" of its file within the chunk dir:
+            // `r.<index>.<encType>.<ext>` for the representation, `.meta.<index>.json`
+            // for the version sidecar. The RAW index segment must pass the same
+            // canonical predicate as the live route (`parseChunkIndexSegment`), so a
+            // non-canonical spelling (`r.01.*`, `r.%31.*`) is dropped rather than
+            // coerced onto -- and colliding with -- the canonical chunk's row.
+            let chunkIdSegment;
+            let representation;
+            let sidecarVersion;
+            const metaId = metaSidecarFileId(fileName);
+            if (metaId !== undefined) {
+                chunkIdSegment = metaId;
+                try {
+                    const sidecar = JSON.parse(entry.body.toString('utf8'));
+                    sidecarVersion = sidecar.version;
+                }
+                catch {
+                    sidecarVersion = undefined;
+                }
+            }
+            else if (fileName.startsWith('r.')) {
+                const { contentType } = parseResourceFileName(fileName);
+                chunkIdSegment = fileName.split('.')[1];
+                representation = { contentType, body: entry.body };
+            }
+            else {
+                continue;
+            }
+            const chunkIndex = chunkIdSegment === undefined
+                ? undefined
+                : parseChunkIndexSegment(chunkIdSegment);
+            if (chunkIndex === undefined) {
+                continue;
+            }
+            const key = `${collectionId}/${resourceId}/${chunkIndex}`;
+            const slot = staged.get(key) ?? { collectionId, resourceId, chunkIndex };
+            if (representation !== undefined) {
+                slot.contentType = representation.contentType;
+                slot.body = representation.body;
+            }
+            if (sidecarVersion !== undefined) {
+                slot.version = sidecarVersion;
+            }
+            staged.set(key, slot);
+        }
+        const parsed = [];
+        for (const slot of staged.values()) {
+            if (slot.body === undefined) {
+                // A sidecar with no paired representation is not a valid chunk.
+                continue;
+            }
+            parsed.push({
+                collectionId: slot.collectionId,
+                resourceId: slot.resourceId,
+                chunkIndex: slot.chunkIndex,
+                contentType: slot.contentType ?? 'application/octet-stream',
+                body: slot.body,
+                version: slot.version
+            });
+        }
+        return parsed;
+    }
 }
 //# sourceMappingURL=postgres.js.map