was-teaching-server 0.9.1 → 0.11.0

package/src/backends/postgres.ts

@@ -42,9 +42,21 @@ import {
   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 type { TarEntry } 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'
@@ -66,6 +78,18 @@ import type {
   BlindedIndexQuery,
   BlindedIndexQueryPage
 } from '../lib/blindedIndex.js'
+import {
+  runEqualityQuery,
+  assertNoUniqueEqualityConflict,
+  findEqualityUniqueViolation
+} from '../lib/equalityIndex.js'
+import type {
+  EqualityQuery,
+  EqualityQueryPage,
+  EqualityCandidate,
+  EqualityValue,
+  NormalizedIndexDeclaration
+} from '../lib/equalityIndex.js'
 import {
   DEFAULT_MAX_UPLOAD_BYTES,
   DEFAULT_MAX_SPACES_PER_CONTROLLER,
@@ -206,6 +230,17 @@ function parseSidecar(bytes: Buffer | undefined): SidecarShape | undefined {
   }
 }
 
+/**
+ * The chunk-metadata sidecar shape (`.chunks.<encId>/.meta.<index>.json`) the
+ * filesystem backend writes per chunk. Only the monotonic `version` (the
+ * chunk's ETag validator) is carried across export/import; the filesystem
+ * writes `createdAt` / `updatedAt` too, but this backend's `chunks` table holds
+ * no chunk timestamps, so it emits and reads only `version`.
+ */
+interface ChunkSidecar {
+  version?: number
+}
+
 export class PostgresBackend implements StorageBackend {
   logger: FastifyBaseLogger
   /**
@@ -421,11 +456,18 @@ export class PostgresBackend implements StorageBackend {
       // `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.
+      // `equality-query`: serves the `equality` profile -- server-extracted
+      // plaintext attribute equality over a Collection's declared `indexes`
+      // (`queryByEquality`), plus the GET `filter[attr]=value` equality filter.
       features: [
         'conditional-writes',
         'changes-query',
         'blinded-index-query',
-        'key-epochs'
+        'equality-query',
+        'key-epochs',
+        'chunked-streams'
       ]
     }
   }
@@ -519,6 +561,42 @@ export class PostgresBackend implements StorageBackend {
     }
   }
 
+  /**
+   * 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>}
+   */
+  private async _lockSameKeyCreate({
+    client,
+    spaceId,
+    rowKey
+  }: {
+    client: pg.PoolClient
+    spaceId: string
+    rowKey: string
+  }): Promise<void> {
+    await client.query(
+      'SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))',
+      [spaceId, `create:${rowKey}`]
+    )
+  }
+
   // Quotas
 
   /**
@@ -546,13 +624,20 @@ export class PostgresBackend implements StorageBackend {
 
     let usageByCollection: CollectionUsage[] | undefined
     if (includeCollections) {
+      // 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<{
         collection_id: string
         usage: string
       }>(
-        `SELECT collection_id, COALESCE(SUM(size_bytes), 0) AS usage
-           FROM resources
-          WHERE space_id = $1
+        `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]
@@ -595,6 +680,8 @@ export class PostgresBackend implements StorageBackend {
          (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]
     )
@@ -1024,9 +1111,15 @@ export class PostgresBackend implements StorageBackend {
     collectionId: string
   }): Promise<void> {
     await this._withTransaction(async client => {
+      // 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<{ total: string }>(
-        `SELECT COALESCE(SUM(size_bytes), 0) AS total FROM resources
-          WHERE space_id = $1 AND collection_id = $2`,
+        `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)
@@ -1203,6 +1296,7 @@ export class PostgresBackend implements StorageBackend {
     input,
     createdBy,
     epoch,
+    uniqueIndexes,
     ifMatch,
     ifNoneMatch
   }: {
@@ -1212,6 +1306,7 @@ export class PostgresBackend implements StorageBackend {
     input: ResourceInput
     createdBy?: IDID
     epoch?: string
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     ifMatch?: string
     ifNoneMatch?: boolean
   }): Promise<{ version: number }> {
@@ -1250,23 +1345,29 @@ export class PostgresBackend implements StorageBackend {
     return this._withTransaction(async client => {
       await this._ensureCollectionRow({ client, spaceId, collectionId })
 
-      // The EDV unique-attribute invariant (`unique: true` blinded attributes;
-      // the `blinded-index-query` feature): a write claiming a unique blinded
-      // triple must not collide with another live document's claim. Only a
-      // unique-carrying JSON write can create a new claim, so only such writes
-      // pay for it: a per-Collection transaction-scoped advisory lock
+      // Two unique-attribute invariants can force a JSON content write to
+      // serialize before it upserts its row: the EDV blinded one (`unique: true`
+      // blinded attributes; the `blinded-index-query` feature) and the plaintext
+      // equality one (a Collection's `unique`-declared `indexes`; the
+      // `equality-query` feature). Only a unique-carrying JSON write can create
+      // either claim. A per-Collection transaction-scoped advisory lock
       // serializes the claimants (held to commit, so the loser's scan sees the
-      // winner's committed row) without entering the row-lock ordering of
-      // plain writes, then the conflict is evaluated against the Collection's
-      // other live JSON documents.
-      if (
+      // winner's committed row) without entering the row-lock ordering of plain
+      // writes; it is taken once and shared by both checks.
+      const blindedUnique =
         input.kind === 'json' &&
         collectUniqueBlindedTerms({ document: input.data }).length > 0
-      ) {
+      const equalityUnique =
+        input.kind === 'json' &&
+        uniqueIndexes !== undefined &&
+        uniqueIndexes.length > 0
+      if (blindedUnique || equalityUnique) {
         await client.query(
           'SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))',
           [spaceId, collectionId]
         )
+      }
+      if (blindedUnique) {
         const { rows: candidateRows } = await client.query<{
           resource_id: string
           content: Buffer | null
@@ -1290,7 +1391,32 @@ export class PostgresBackend implements StorageBackend {
             // skip an unparsable body
           }
         }
-        assertNoUniqueBlindedConflict({ document: input.data, candidates })
+        assertNoUniqueBlindedConflict({
+          document: input.kind === 'json' ? input.data : undefined,
+          candidates
+        })
+      }
+      if (equalityUnique) {
+        // A content write does not change the Resource's `custom`, so the custom
+        // side of the claim comes from the CURRENT stored row.
+        const { rows: selfRows } = await client.query<{
+          custom: ResourceMetadataCustom | Record<string, unknown> | null
+        }>(
+          `SELECT custom FROM resources
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
+              AND NOT deleted`,
+          [spaceId, collectionId, resourceId]
+        )
+        assertNoUniqueEqualityConflict({
+          indexes: uniqueIndexes!,
+          content: input.kind === 'json' ? input.data : undefined,
+          custom: selfRows[0]?.custom ?? undefined,
+          candidates: await this._readEqualityCandidates(client, {
+            spaceId,
+            collectionId,
+            excludeResourceId: resourceId
+          })
+        })
       }
 
       // Narrow projection: the lock needs the row, not its (possibly multi-MB)
@@ -1307,7 +1433,31 @@ export class PostgresBackend implements StorageBackend {
           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<
+          Pick<
+            ResourceRow,
+            'version' | 'size_bytes' | 'deleted' | 'created_at' | 'created_by'
+          >
+        >(
+          `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({
@@ -1339,7 +1489,7 @@ export class PostgresBackend implements StorageBackend {
 
       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 })
@@ -1350,10 +1500,11 @@ export class PostgresBackend implements StorageBackend {
       // 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
@@ -1519,7 +1670,25 @@ export class PostgresBackend implements StorageBackend {
         // 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<{ total: string }>(
+        `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 })
       }
@@ -1615,6 +1784,7 @@ export class PostgresBackend implements StorageBackend {
     resourceId,
     custom,
     epoch,
+    uniqueIndexes,
     ifMatch,
     ifNoneMatch
   }: {
@@ -1623,10 +1793,24 @@ export class PostgresBackend implements StorageBackend {
     resourceId: string
     custom: ResourceMetadataCustom | Record<string, unknown>
     epoch?: string
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     ifMatch?: string
     ifNoneMatch?: boolean
   }): Promise<{ metaVersion: number } | undefined> {
     return this._withTransaction(async client => {
+      // A metadata write can create a plaintext equality unique claim for a
+      // `custom`-sourced attribute (the `equality-query` feature). When the
+      // Collection declares any unique index, take the per-Collection advisory
+      // lock first (held to commit, serializing concurrent claimants) so the
+      // conflict scan below is atomic with the write.
+      const equalityUnique =
+        uniqueIndexes !== undefined && uniqueIndexes.length > 0
+      if (equalityUnique) {
+        await client.query(
+          'SELECT pg_advisory_xact_lock(hashtext($1), hashtext($2))',
+          [spaceId, collectionId]
+        )
+      }
       const { rows } = await client.query<ResourceRow>(
         `SELECT meta_version, deleted FROM resources
           WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3
@@ -1643,6 +1827,39 @@ export class PostgresBackend implements StorageBackend {
         ifMatch,
         ifNoneMatch
       })
+      if (equalityUnique) {
+        // Content is the Resource's stored JSON content (unchanged by a
+        // metadata write); custom is the incoming value this write sets. Fetch
+        // the (possibly multi-MB) content only on this uniqueness path -- the
+        // row is already `FOR UPDATE`-locked above.
+        const { rows: selfRows } = await client.query<{
+          content: Buffer | null
+          is_json: boolean
+        }>(
+          `SELECT content, is_json FROM resources
+            WHERE space_id = $1 AND collection_id = $2 AND resource_id = $3`,
+          [spaceId, collectionId, resourceId]
+        )
+        let content: unknown
+        const selfRow = selfRows[0]
+        if (selfRow?.is_json && selfRow.content) {
+          try {
+            content = JSON.parse(selfRow.content.toString('utf8')) as unknown
+          } catch {
+            content = undefined
+          }
+        }
+        assertNoUniqueEqualityConflict({
+          indexes: uniqueIndexes!,
+          content,
+          custom,
+          candidates: await this._readEqualityCandidates(client, {
+            spaceId,
+            collectionId,
+            excludeResourceId: resourceId
+          })
+        })
+      }
       const metaVersion = (prior.meta_version ?? 0) + 1
       const hasCustom = Object.keys(custom).length > 0
       const now = new Date().toISOString()
@@ -1671,6 +1888,395 @@ export class PostgresBackend implements StorageBackend {
     })
   }
 
+  // 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
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    input: ResourceInput
+    ifMatch?: string
+    ifNoneMatch?: boolean
+  }): Promise<{ version: number }> {
+    const { maxUploadBytes } = this
+    let bytes: Buffer
+    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<{ deleted: boolean }>(
+        `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<{ version: number; size: string }>(
+        `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<{
+          version: number
+          size: string
+        }>(
+          `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 as { code?: string }).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<{ version: number }>(
+        `${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
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<ResourceResult> {
+    const { rows } = await this._pool.query<{
+      content_type: string
+      bytes: Buffer
+      version: number
+    }>(
+      `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
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<
+    { contentType: string; size: number; version?: number } | undefined
+  > {
+    const { rows } = await this._pool.query<{
+      content_type: string
+      size: string
+      version: number
+    }>(
+      `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
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    ifMatch?: string
+  }): Promise<boolean> {
+    return this._withTransaction(async client => {
+      const { rows } = await client.query<{ version: number; size: string }>(
+        `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
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+  }): Promise<{
+    count: number
+    chunks: Array<{
+      index: number
+      size: number
+      contentType: string
+      version?: number
+    }>
+  }> {
+    const { rows } = await this._pool.query<{
+      chunk_index: number
+      size: string
+      content_type: string
+      version: number
+    }>(
+      `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
@@ -1834,6 +2440,145 @@ export class PostgresBackend implements StorageBackend {
     return runBlindedIndexQuery({ candidates, query, count, limit, cursor })
   }
 
+  /**
+   * Plaintext equality query (the `equality` query profile; see the
+   * `StorageBackend.queryByEquality` contract). Reads the Collection's live
+   * Resources -- JSON rows carrying parsed `content`, all rows carrying their
+   * `custom` jsonb -- and hands the candidates to the shared evaluator
+   * (`lib/equalityIndex.ts`) for extraction, matching, ordering, and cursor
+   * pagination -- identical semantics to the filesystem backend. A full scan of
+   * the Collection per call, deliberate for this teaching backend; a
+   * materialized variant would answer from a JSONB expression index.
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param options.query {EqualityQuery}
+   * @param options.indexes {NormalizedIndexDeclaration[]}
+   * @param [options.count] {boolean}   return only the match count
+   * @param [options.limit] {number}   requested page size
+   * @param [options.cursor] {string}   opaque cursor from a prior page
+   * @returns {Promise<{ count: number } | EqualityQueryPage>}
+   */
+  async queryByEquality({
+    spaceId,
+    collectionId,
+    query,
+    indexes,
+    count,
+    limit,
+    cursor
+  }: {
+    spaceId: string
+    collectionId: string
+    query: EqualityQuery
+    indexes: NormalizedIndexDeclaration[]
+    count?: boolean
+    limit?: number
+    cursor?: string
+  }): Promise<{ count: number } | EqualityQueryPage> {
+    const candidates = await this._readEqualityCandidates(this._pool, {
+      spaceId,
+      collectionId
+    })
+    return runEqualityQuery({
+      candidates,
+      query,
+      indexes,
+      count,
+      limit,
+      cursor
+    })
+  }
+
+  /**
+   * Declare-time uniqueness scan for the `equality` profile (see the
+   * `StorageBackend.findEqualityUniqueViolation` contract): reads the
+   * Collection's live Resources and delegates to the shared scan, which reports
+   * the first `(name, value)` claimed by two different Resources under the given
+   * `unique` declarations (or `undefined` when none is).
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param options.indexes {NormalizedIndexDeclaration[]}
+   * @returns {Promise<{ name: string, value: EqualityValue } | undefined>}
+   */
+  async findEqualityUniqueViolation({
+    spaceId,
+    collectionId,
+    indexes
+  }: {
+    spaceId: string
+    collectionId: string
+    indexes: NormalizedIndexDeclaration[]
+  }): Promise<{ name: string; value: EqualityValue } | undefined> {
+    const candidates = await this._readEqualityCandidates(this._pool, {
+      spaceId,
+      collectionId
+    })
+    return findEqualityUniqueViolation({ indexes, candidates })
+  }
+
+  /**
+   * Reads every live Resource of a Collection as an equality candidate -- the
+   * candidate set for the equality query and the plaintext unique-attribute
+   * conflict scans. Includes blob Resources (queryable through their
+   * `custom`-sourced attributes): each row resolves `{ resourceId, content?,
+   * custom? }`, where `content` is the parsed JSON of a JSON row (a blob and
+   * unparsable JSON contribute none) and `custom` is the row's jsonb `custom`
+   * when set. Tombstones are excluded (`NOT deleted`); an optional excluded
+   * Resource is skipped. Runs on the given executor -- the pool for a read-only
+   * query, or the write transaction's client for a uniqueness scan (so the scan
+   * shares the advisory lock and sees a consistent snapshot).
+   * @param executor {pg.Pool | pg.PoolClient}
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param [options.excludeResourceId] {string}
+   * @returns {Promise<EqualityCandidate[]>}
+   */
+  private async _readEqualityCandidates(
+    executor: pg.Pool | pg.PoolClient,
+    {
+      spaceId,
+      collectionId,
+      excludeResourceId
+    }: {
+      spaceId: string
+      collectionId: string
+      excludeResourceId?: string
+    }
+  ): Promise<EqualityCandidate[]> {
+    const { rows } = await executor.query<{
+      resource_id: string
+      content: Buffer | null
+      is_json: boolean
+      custom: ResourceMetadataCustom | Record<string, unknown> | null
+    }>(
+      `SELECT resource_id, content, is_json, custom FROM resources
+        WHERE space_id = $1 AND collection_id = $2 AND NOT deleted
+          AND ($3::text IS NULL OR resource_id <> $3)
+        ORDER BY resource_id`,
+      [spaceId, collectionId, excludeResourceId ?? null]
+    )
+    const candidates: EqualityCandidate[] = []
+    for (const row of rows) {
+      let content: unknown
+      if (row.is_json && row.content) {
+        try {
+          content = JSON.parse(row.content.toString('utf8')) as unknown
+        } catch {
+          // skip an unparsable body -- it contributes no content attributes
+        }
+      }
+      candidates.push({
+        resourceId: row.resource_id,
+        ...(content !== undefined && { content }),
+        ...(row.custom !== null && { custom: row.custom })
+      })
+    }
+    return candidates
+  }
+
   // Policies
 
   /**
@@ -2435,7 +3180,8 @@ export class PostgresBackend implements StorageBackend {
       { rows: policyRows },
       { rows: collectionRows },
       { rows: resourceRows },
-      { rows: revocationRows }
+      { rows: revocationRows },
+      { rows: chunkRows }
     ] = await Promise.all([
       this._pool.query<{
         collection_id: string
@@ -2477,6 +3223,20 @@ export class PostgresBackend implements StorageBackend {
         `SELECT delegator, capability_id, record FROM space_revocations
             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<{
+        collection_id: string
+        resource_id: string
+        chunk_index: number
+        content_type: string
+        version: number
+      }>(
+        `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]
       )
     ])
 
@@ -2487,11 +3247,26 @@ export class PostgresBackend implements StorageBackend {
       row => row.collection_id === '' && row.resource_id === ''
     )?.policy
 
-    // A file entry carries its bytes inline (the small JSON dot-files) or a
-    // lazy reference to a resource representation, resolved at pack time.
+    // A file entry carries its bytes inline (the small JSON dot-files), a lazy
+    // reference to a resource representation, or a chunk directory (the
+    // `chunked-streams` feature) whose files are likewise inline (the per-chunk
+    // `.meta.<index>.json` sidecar) or lazy (the chunk `r.<index>...`
+    // representation, resolved at pack time). `name` is the entry's sort key
+    // within its dir; a chunk directory sorts by its `.chunks.<encId>` dir name.
+    type ChunkFile =
+      | { name: string; bytes: Buffer }
+      | {
+          name: string
+          chunk: {
+            collectionId: string
+            resourceId: string
+            chunkIndex: number
+          }
+        }
     type FileEntry =
       | { name: string; bytes: Buffer }
       | { name: string; resource: { collectionId: string; resourceId: string } }
+      | { name: string; chunkDir: ChunkFile[] }
     // Space-level dot-files are always small JSON, carried inline.
     const spaceFiles: Array<{ name: string; bytes: Buffer }> = [
       {
@@ -2564,6 +3339,48 @@ export class PostgresBackend implements StorageBackend {
         })
       }
     }
+    // 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<string, ChunkFile[]>()
+    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 } satisfies ChunkSidecar)
+        )
+      })
+    }
+    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.
@@ -2597,7 +3414,17 @@ export class PostgresBackend implements StorageBackend {
       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)
@@ -2615,6 +3442,25 @@ export class PostgresBackend implements StorageBackend {
       if (entry.kind === 'collection') {
         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
@@ -2663,6 +3509,38 @@ export class PostgresBackend implements StorageBackend {
     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>}
+   */
+  private async _chunkContent({
+    spaceId,
+    collectionId,
+    resourceId,
+    chunkIndex
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<Buffer> {
+    const { rows } = await this._pool.query<{ bytes: Buffer | null }>(
+      `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
@@ -2685,6 +3563,10 @@ export class PostgresBackend implements StorageBackend {
   }): Promise<ImportStats> {
     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,
@@ -2774,6 +3656,19 @@ export class PostgresBackend implements StorageBackend {
           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
@@ -2966,13 +3861,63 @@ export class PostgresBackend implements StorageBackend {
         }
       }
 
-      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<{ deleted: boolean }>(
+          `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
         })
       }
 
@@ -3070,4 +4015,141 @@ export class PostgresBackend implements StorageBackend {
       ]
     )
   }
+
+  /**
+   * 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 }>}
+   */
+  private _chunkEntriesFromArchive(entries: Map<string, TarEntry>): Array<{
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    contentType: string
+    body: Buffer
+    version?: number
+  }> {
+    // 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<
+      string,
+      {
+        collectionId: string
+        resourceId: string
+        chunkIndex: number
+        contentType?: string
+        body?: Buffer
+        version?: number
+      }
+    >()
+    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: string | undefined
+      let representation: { contentType: string; body: Buffer } | undefined
+      let sidecarVersion: number | undefined
+      const metaId = metaSidecarFileId(fileName)
+      if (metaId !== undefined) {
+        chunkIdSegment = metaId
+        try {
+          const sidecar = JSON.parse(
+            entry.body.toString('utf8')
+          ) as ChunkSidecar
+          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: Array<{
+      collectionId: string
+      resourceId: string
+      chunkIndex: number
+      contentType: string
+      body: Buffer
+      version?: number
+    }> = []
+    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
+  }
 }