was-teaching-server 0.9.1 → 0.11.0

package/src/backends/filesystem.ts

@@ -44,7 +44,9 @@ import { collectionPath, resourcePath } from '../lib/paths.js'
 import {
   encodeFilenameSegment,
   fileNameFor,
-  parseResourceFileName
+  parseResourceFileName,
+  chunkDirName,
+  CHUNK_DIR_PREFIX
 } from '../lib/resourceFileName.js'
 import { sanitizeBackendRecord } from '../lib/backends.js'
 import { backendUsageFields } from '../lib/backendUsage.js'
@@ -74,6 +76,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 {
   assertWritePrecondition,
   assertMetaWritePrecondition,
@@ -373,8 +387,9 @@ export class FileSystemBackend implements StorageBackend {
    * It advertises the `conditional-writes` affordance: it exposes a per-Resource
    * `version` as an HTTP `ETag` validator and honors `If-Match` / `If-None-Match`
    * write preconditions atomically (returning `412 precondition-failed` on a
-   * mismatch). The remaining `features` vocabulary token (`chunked-streams`)
-   * is not implemented yet and is added when it lands.
+   * mismatch). It also advertises `chunked-streams`: chunk addressing for large
+   * Resources (`/{resourceId}/chunks/{n}`), each chunk stored opaquely like a
+   * binary Resource representation.
    * (Client-side encryption is deliberately not a backend feature: encrypted
    * documents are opaque client-encrypted JSON this backend already stores
    * faithfully, with no server cooperation.)
@@ -399,11 +414,18 @@ export class FileSystemBackend 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 (`/{resourceId}/chunks/{n}`) for a
+      // large Resource, each chunk stored opaquely (bytes + content-type).
+      // `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'
       ]
     }
   }
@@ -1096,6 +1118,14 @@ export class FileSystemBackend implements StorageBackend {
     spaceEntries.sort((a, b) => a.name.localeCompare(b.name))
 
     const collectionEntriesByDir: Record<string, typeof spaceEntries> = {}
+    // Per-Resource chunk directories (`.chunks.<encId>/`; the `chunked-streams`
+    // feature) are subdirectories of a Collection dir, so the file filter below
+    // skips them. Gather each one's files here so a chunked Resource's chunks
+    // travel in the export, keyed by Collection then by chunk-directory name.
+    const chunkDirsByCollection: Record<
+      string,
+      Array<{ dirName: string; files: string[] }>
+    > = {}
     for (const entry of spaceEntries) {
       if (!entry.isDirectory()) {
         continue
@@ -1107,6 +1137,22 @@ export class FileSystemBackend implements StorageBackend {
       collectionEntriesByDir[entry.name] = entries
         .filter(e => e.isFile())
         .sort((a, b) => a.name.localeCompare(b.name))
+      const chunkDirs: Array<{ dirName: string; files: string[] }> = []
+      for (const sub of entries
+        .filter(e => e.isDirectory() && e.name.startsWith(CHUNK_DIR_PREFIX))
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const files = (
+          await fs.promises.readdir(
+            path.join(sourceSpaceDir, entry.name, sub.name),
+            { withFileTypes: true }
+          )
+        )
+          .filter(e => e.isFile())
+          .map(e => e.name)
+          .sort((a, b) => a.localeCompare(b))
+        chunkDirs.push({ dirName: sub.name, files })
+      }
+      chunkDirsByCollection[entry.name] = chunkDirs
     }
 
     // Space-scoped zcap revocations travel with the export. They live in the
@@ -1135,9 +1181,18 @@ export class FileSystemBackend implements StorageBackend {
         entry.isDirectory()
           ? {
               name: entry.name,
-              files: (collectionEntriesByDir[entry.name] ?? []).map(
-                file => file.name
-              )
+              // The Collection's own files, then each chunked Resource's chunk
+              // files listed by their `.chunks.<encId>/<file>` relative path
+              // (the manifest mirrors the pack order below).
+              files: [
+                ...(collectionEntriesByDir[entry.name] ?? []).map(
+                  file => file.name
+                ),
+                ...(chunkDirsByCollection[entry.name] ?? []).flatMap(
+                  ({ dirName, files }) =>
+                    files.map(file => `${dirName}/${file}`)
+                )
+              ]
             }
           : // top-level files in space (e.g. .space.<spaceId>.json)
             { name: entry.name }
@@ -1164,6 +1219,25 @@ export class FileSystemBackend implements StorageBackend {
           )
           pack.entry({ name: `${entryTarget}/${file.name}`, mtime }, bytes)
         }
+        // A chunked Resource's chunk directory and its files, packed under the
+        // Collection so `.chunks.<encId>/<file>` round-trips on import.
+        for (const { dirName, files } of chunkDirsByCollection[entry.name] ??
+          []) {
+          pack.entry({
+            name: `${entryTarget}/${dirName}/`,
+            type: 'directory',
+            mtime
+          })
+          for (const file of files) {
+            const bytes = await fs.promises.readFile(
+              path.join(sourceSpaceDir, entry.name, dirName, file)
+            )
+            pack.entry(
+              { name: `${entryTarget}/${dirName}/${file}`, mtime },
+              bytes
+            )
+          }
+        }
       } else if (entry.isFile()) {
         const bytes = await fs.promises.readFile(
           path.join(sourceSpaceDir, entry.name)
@@ -1226,7 +1300,8 @@ export class FileSystemBackend implements StorageBackend {
     for (const {
       collectionId,
       collectionDescription,
-      resources
+      resources,
+      chunkFiles
     } of collections) {
       const existing = await this.getCollectionDescription({
         spaceId,
@@ -1259,6 +1334,19 @@ export class FileSystemBackend implements StorageBackend {
         }
         incomingBytes += body.length
       }
+      // Chunk files (the `chunked-streams` feature) inherit the per-upload cap
+      // and quota estimate, but NOT the encryption-conformance check: a chunk is
+      // opaque bytes, not a JSON envelope of the Collection's scheme.
+      for (const { body } of chunkFiles) {
+        if (maxUploadBytes !== undefined && body.length > maxUploadBytes) {
+          throw new PayloadTooLargeError({
+            maxUploadBytes,
+            backendId: this.describe().id,
+            uploadBytes: body.length
+          })
+        }
+        incomingBytes += body.length
+      }
     }
     if (capacityBytes !== undefined) {
       await this._assertSpaceHeadroom({
@@ -1309,7 +1397,8 @@ export class FileSystemBackend implements StorageBackend {
       collectionPolicy,
       resources,
       resourcePolicies,
-      resourceMetadata
+      resourceMetadata,
+      chunkFiles
     } of collections) {
       // check if collection already exists
       const collectionExisted = Boolean(
@@ -1451,6 +1540,43 @@ export class FileSystemBackend implements StorageBackend {
         })
         stats.resourcesCreated++
       }
+
+      // Restore chunk files of chunked Resources (the `chunked-streams` feature)
+      // into their per-Resource chunk directories. Skip-not-overwrite, per chunk
+      // file: an existing chunk file is left untouched, so a re-import never
+      // clobbers stored chunk bytes (or their version sidecar). An ORPHAN chunk
+      // file -- one whose parent Resource is absent or a tombstone (no live
+      // representation on the destination after the Resource apply loop above)
+      // -- is skipped rather than resurrected, matching the live write path's
+      // parent-exists rule (and the Postgres import).
+      const parentIsLive = new Map<string, boolean>()
+      for (const { resourceId, fileName, body } of chunkFiles) {
+        let live = parentIsLive.get(resourceId)
+        if (live === undefined) {
+          live = Boolean(await this._findFile({ collectionDir, resourceId }))
+          parentIsLive.set(resourceId, live)
+        }
+        if (!live) {
+          continue
+        }
+        const chunkDir = this._chunkDir({ collectionDir, resourceId })
+        const target = path.join(chunkDir, fileName)
+        this._assertContained(target)
+        let present = false
+        try {
+          await fsStat(target)
+          present = true
+        } catch (err) {
+          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+            throw err
+          }
+        }
+        if (present) {
+          continue
+        }
+        await mkdir(chunkDir, { recursive: true })
+        await atomicWriteFile({ filePath: target, data: body })
+      }
     }
 
     // Restore the archive's Space-scoped zcap revocations under this Space's
@@ -1887,6 +2013,7 @@ export class FileSystemBackend implements StorageBackend {
     input,
     createdBy,
     epoch,
+    uniqueIndexes,
     ifMatch,
     ifNoneMatch
   }: {
@@ -1896,6 +2023,7 @@ export class FileSystemBackend implements StorageBackend {
     input: ResourceInput
     createdBy?: IDID
     epoch?: string
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     ifMatch?: string
     ifNoneMatch?: boolean
   }): Promise<{ version: number }> {
@@ -1919,30 +2047,57 @@ export class FileSystemBackend implements StorageBackend {
         })
       )
 
-    // 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: they serialize per Collection (the outer lock, so two racing
-    // claimants cannot both pass the scan), evaluate the conflict against the
-    // Collection's other live JSON documents, then take the ordinary
-    // per-Resource lock nested inside. Distinct-key nesting cannot deadlock:
-    // plain writes never hold a Resource key while waiting on a Collection key.
-    if (
+    // Two unique-attribute invariants can force a write to serialize on the
+    // Collection lock before it takes its per-Resource lock: 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 JSON content write can
+    // create either claim, so only such writes pay for it: they serialize per
+    // Collection (the outer lock, so two racing claimants cannot both pass the
+    // scan), evaluate the conflict against the Collection's other live
+    // documents, then take the ordinary per-Resource lock nested inside.
+    // Distinct-key nesting cannot deadlock: plain writes never hold a Resource
+    // key while waiting on a Collection key. The two conditions are unified so a
+    // write carrying both claims acquires the Collection lock exactly once.
+    const blindedUnique =
       input.kind === 'json' &&
       collectUniqueBlindedTerms({ document: input.data }).length > 0
-    ) {
+    const equalityUnique =
+      input.kind === 'json' &&
+      uniqueIndexes !== undefined &&
+      uniqueIndexes.length > 0
+    if (blindedUnique || equalityUnique) {
       return this._writeMutex.run(
         this._collectionLockKey({ spaceId, collectionId }),
         async () => {
-          assertNoUniqueBlindedConflict({
-            document: input.data,
-            candidates: await this._readJsonCandidates({
-              spaceId,
-              collectionId,
-              excludeResourceId: resourceId
+          if (blindedUnique) {
+            assertNoUniqueBlindedConflict({
+              document: input.kind === 'json' ? input.data : undefined,
+              candidates: await this._readJsonCandidates({
+                spaceId,
+                collectionId,
+                excludeResourceId: resourceId
+              })
             })
-          })
+          }
+          if (equalityUnique) {
+            // A content write does not change the Resource's `custom`, so the
+            // custom side of the claim comes from the CURRENT stored sidecar.
+            const priorSidecar = await this._readMetaSidecar({
+              collectionDir,
+              resourceId
+            })
+            assertNoUniqueEqualityConflict({
+              indexes: uniqueIndexes!,
+              content: input.kind === 'json' ? input.data : undefined,
+              custom: priorSidecar?.custom,
+              candidates: await this._readEqualityCandidates({
+                spaceId,
+                collectionId,
+                excludeResourceId: resourceId
+              })
+            })
+          }
           return write()
         }
       )
@@ -2009,6 +2164,83 @@ export class FileSystemBackend implements StorageBackend {
       }
     }
 
+    await this._writeRepresentationBytes({ spaceId, filePath, input })
+
+    // A Resource has a single current representation: remove any prior
+    // representation stored under a different content-type (its filename
+    // differs). Write-new-then-prune (not delete-then-write) so the resource is
+    // never momentarily absent.
+    const existing = await this._resourceFilesFor({ collectionDir, resourceId })
+    await Promise.all(
+      existing
+        .filter(name => path.resolve(name) !== path.resolve(filePath))
+        .map(name => rm(name))
+    )
+
+    // Maintain the server-managed timestamps and the monotonic `version`: a
+    // content write sets `createdAt` on first write, bumps `updatedAt`, and
+    // increments `version` (the ETag validator) from its prior value, preserving
+    // any user-writable `custom` and the independent `metaVersion` already stored
+    // in the sidecar (a content write does not touch the metadata sub-resource).
+    //
+    // `createdBy` pairs with `createdAt`: taken from this write's invoker only
+    // when this write creates the sidecar, so it names the creator rather than
+    // the last writer, and is preserved verbatim afterward -- including
+    // preserved-as-absent, so a Resource created with no invoker never has a
+    // later writer backfilled into it. A tombstone keeps both, so re-creating a
+    // deleted id under a different invoker preserves the original creator, as
+    // it does the original `createdAt`.
+    const now = new Date().toISOString()
+    const prior = await this._readMetaSidecar({ collectionDir, resourceId })
+    const version = (prior?.version ?? 0) + 1
+    const creator = prior ? prior.createdBy : createdBy
+    await this._writeMetaSidecar({
+      collectionDir,
+      resourceId,
+      sidecar: {
+        createdAt: prior?.createdAt ?? now,
+        updatedAt: now,
+        ...(creator !== undefined && { createdBy: creator }),
+        version,
+        ...(prior?.metaVersion !== undefined && {
+          metaVersion: prior.metaVersion
+        }),
+        ...(prior?.custom && { custom: prior.custom }),
+        // The key-epoch stamp is set from this write's declaration and CLEARED
+        // when absent (the new ciphertext's epoch is unknown -- a stale stamp is
+        // worse than none), so it is NOT preserved from `prior` like `custom`.
+        ...(epoch !== undefined && { epoch })
+      }
+    })
+    return { version }
+  }
+
+  /**
+   * Writes a representation body (JSON value or byte stream) to `filePath`,
+   * applying the same size guards every write path shares: the per-upload cap
+   * (413 `PayloadTooLargeError`) and, when a byte quota is configured, the
+   * Space headroom (507). A JSON body is fully in memory, so its size is checked
+   * up front and written atomically; a binary body is streamed through the cap /
+   * quota guards into a temp file and durably committed (fsync + rename + dir
+   * fsync), removing the partial file on any failure. Shared by the Resource
+   * write path (`_writeResourceLocked`) and the chunk write path
+   * (`_writeChunkLocked`); the caller has already resolved `filePath` and ensured
+   * its parent directory exists for the streamed case.
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.filePath {string}   absolute path of the representation file
+   * @param options.input {ResourceInput}
+   * @returns {Promise<void>}
+   */
+  private async _writeRepresentationBytes({
+    spaceId,
+    filePath,
+    input
+  }: {
+    spaceId: string
+    filePath: string
+    input: ResourceInput
+  }): Promise<void> {
     const { capacityBytes, maxUploadBytes } = this
 
     if (input.kind === 'json') {
@@ -2098,54 +2330,6 @@ export class FileSystemBackend implements StorageBackend {
         throw err
       }
     }
-
-    // A Resource has a single current representation: remove any prior
-    // representation stored under a different content-type (its filename
-    // differs). Write-new-then-prune (not delete-then-write) so the resource is
-    // never momentarily absent.
-    const existing = await this._resourceFilesFor({ collectionDir, resourceId })
-    await Promise.all(
-      existing
-        .filter(name => path.resolve(name) !== path.resolve(filePath))
-        .map(name => rm(name))
-    )
-
-    // Maintain the server-managed timestamps and the monotonic `version`: a
-    // content write sets `createdAt` on first write, bumps `updatedAt`, and
-    // increments `version` (the ETag validator) from its prior value, preserving
-    // any user-writable `custom` and the independent `metaVersion` already stored
-    // in the sidecar (a content write does not touch the metadata sub-resource).
-    //
-    // `createdBy` pairs with `createdAt`: taken from this write's invoker only
-    // when this write creates the sidecar, so it names the creator rather than
-    // the last writer, and is preserved verbatim afterward -- including
-    // preserved-as-absent, so a Resource created with no invoker never has a
-    // later writer backfilled into it. A tombstone keeps both, so re-creating a
-    // deleted id under a different invoker preserves the original creator, as
-    // it does the original `createdAt`.
-    const now = new Date().toISOString()
-    const prior = await this._readMetaSidecar({ collectionDir, resourceId })
-    const version = (prior?.version ?? 0) + 1
-    const creator = prior ? prior.createdBy : createdBy
-    await this._writeMetaSidecar({
-      collectionDir,
-      resourceId,
-      sidecar: {
-        createdAt: prior?.createdAt ?? now,
-        updatedAt: now,
-        ...(creator !== undefined && { createdBy: creator }),
-        version,
-        ...(prior?.metaVersion !== undefined && {
-          metaVersion: prior.metaVersion
-        }),
-        ...(prior?.custom && { custom: prior.custom }),
-        // The key-epoch stamp is set from this write's declaration and CLEARED
-        // when absent (the new ciphertext's epoch is unknown -- a stale stamp is
-        // worse than none), so it is NOT preserved from `prior` like `custom`.
-        ...(epoch !== undefined && { epoch })
-      }
-    })
-    return { version }
   }
 
   /**
@@ -2456,6 +2640,7 @@ export class FileSystemBackend implements StorageBackend {
     resourceId,
     custom,
     epoch,
+    uniqueIndexes,
     ifMatch,
     ifNoneMatch
   }: {
@@ -2464,6 +2649,7 @@ export class FileSystemBackend implements StorageBackend {
     resourceId: string
     custom: ResourceMetadataCustom | Record<string, unknown>
     epoch?: string
+    uniqueIndexes?: NormalizedIndexDeclaration[]
     ifMatch?: string
     ifNoneMatch?: boolean
   }): Promise<{ metaVersion: number } | undefined> {
@@ -2525,6 +2711,38 @@ export class FileSystemBackend implements StorageBackend {
       })
       return { metaVersion }
     }
+    // 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, serialize on the Collection lock and
+    // scan for a conflict -- content is the Resource's stored JSON content
+    // (unchanged by a metadata write), custom is the incoming value this write
+    // sets -- before taking the per-Resource lock nested inside. Distinct-key
+    // nesting cannot deadlock (plain writes never hold a Resource key while
+    // waiting on a Collection key).
+    if (uniqueIndexes !== undefined && uniqueIndexes.length > 0) {
+      return this._writeMutex.run(
+        this._collectionLockKey({ spaceId, collectionId }),
+        async () => {
+          assertNoUniqueEqualityConflict({
+            indexes: uniqueIndexes,
+            content: await this._readResourceJsonContent({
+              collectionDir,
+              resourceId
+            }),
+            custom,
+            candidates: await this._readEqualityCandidates({
+              spaceId,
+              collectionId,
+              excludeResourceId: resourceId
+            })
+          })
+          return this._writeMutex.run(
+            this._resourceLockKey({ spaceId, collectionId, resourceId }),
+            writeMeta
+          )
+        }
+      )
+    }
     return this._writeMutex.run(
       this._resourceLockKey({ spaceId, collectionId, resourceId }),
       writeMeta
@@ -2598,6 +2816,15 @@ export class FileSystemBackend implements StorageBackend {
       )
       // Drop the content representation(s) but KEEP the sidecar as the tombstone.
       await Promise.all(filesForResource.map(filename => rm(filename)))
+      // Cascade-delete the Resource's chunks (the `chunked-streams` feature): a
+      // chunk must never outlive its parent Resource, so its whole chunk
+      // directory goes with the content. Runs under the same per-Resource lock a
+      // `writeChunk` takes, so a chunk write racing this delete cannot re-create
+      // an orphan directory. `force` makes an absent chunk directory a no-op.
+      await rm(this._chunkDir({ collectionDir, resourceId }), {
+        recursive: true,
+        force: true
+      })
       // Bump `version` / `updatedAt` so the tombstone sorts after the Resource's
       // prior state in the change feed, and continues the monotonic version (a
       // later re-create reads this sidecar and keeps counting up). `custom` is
@@ -2630,6 +2857,439 @@ export class FileSystemBackend implements StorageBackend {
     )
   }
 
+  // Chunks (the `chunked-streams` feature)
+
+  /**
+   * Builds the on-disk path for a Resource's chunk directory
+   * (`.chunks.<encodedResourceId>/`) inside its Collection dir. A hidden
+   * subdirectory (leading `.`, so it is invisible to the `r.`-prefixed Collection
+   * listing and the live-Resource count) that holds the Resource's chunk
+   * representations; inside it a chunk is stored exactly like a Resource keyed by
+   * its index (`r.<index>.<encodedContentType>.<ext>` plus a `.meta.<index>.json`
+   * version sidecar), so the Resource file / sidecar helpers are reused verbatim
+   * with the chunk directory as the `collectionDir`.
+   * @param options {object}
+   * @param options.collectionDir {string}
+   * @param options.resourceId {string}
+   * @returns {string}
+   */
+  _chunkDir({
+    collectionDir,
+    resourceId
+  }: {
+    collectionDir: string
+    resourceId: string
+  }): string {
+    const chunkDir = path.join(collectionDir, chunkDirName(resourceId))
+    this._assertContained(chunkDir)
+    return chunkDir
+  }
+
+  /**
+   * Writes one chunk of a chunked Resource, keyed by
+   * `(spaceId, collectionId, resourceId, chunkIndex)`. The parent Resource MUST
+   * already exist (else `ResourceNotFoundError`, 404), checked under the same
+   * per-Resource lock a `deleteResource` cascade takes so a chunk can never be
+   * orphaned by a racing delete. The body is stored opaquely (bytes +
+   * content-type) through the shared upload-cap / quota guards, and the chunk's
+   * own monotonic `version` (its ETag validator, independent of the parent's) is
+   * bumped; any `If-Match` / `If-None-Match` precondition is evaluated on that
+   * version atomically with the write (`PreconditionFailedError`, 412).
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param options.resourceId {string}
+   * @param options.chunkIndex {number}   non-negative integer chunk position
+   * @param options.input {ResourceInput}
+   * @param [options.ifMatch] {string}   `If-Match` precondition (a quoted ETag)
+   * @param [options.ifNoneMatch] {boolean}   `If-None-Match: *` (create-if-absent)
+   * @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 collectionDir = this._collectionDir({ spaceId, collectionId })
+    // Serialize on the parent Resource's lock key -- the same key
+    // `deleteResource` takes -- so the parent-exists check, the write, and the
+    // cascade delete cannot interleave (no orphan chunk).
+    return this._writeMutex.run(
+      this._resourceLockKey({ spaceId, collectionId, resourceId }),
+      () =>
+        this._writeChunkLocked({
+          spaceId,
+          collectionDir,
+          resourceId,
+          chunkIndex,
+          input,
+          ifMatch,
+          ifNoneMatch
+        })
+    )
+  }
+
+  /**
+   * The critical section of `writeChunk`, run under the per-Resource lock. See
+   * `writeChunk` for the parameters.
+   * @returns {Promise<{ version: number }>}
+   */
+  private async _writeChunkLocked({
+    spaceId,
+    collectionDir,
+    resourceId,
+    chunkIndex,
+    input,
+    ifMatch,
+    ifNoneMatch
+  }: {
+    spaceId: string
+    collectionDir: string
+    resourceId: string
+    chunkIndex: number
+    input: ResourceInput
+    ifMatch?: string
+    ifNoneMatch?: boolean
+  }): Promise<{ version: number }> {
+    // The parent Resource must exist: writing a chunk of an absent Resource
+    // rejects, so orphan chunks cannot accumulate.
+    const parentExists =
+      (await this._findFile({ collectionDir, resourceId })) !== undefined
+    if (!parentExists) {
+      throw new ResourceNotFoundError({ requestName: 'Write Chunk' })
+    }
+
+    // Inside the chunk directory a chunk is a Resource keyed by its index, so the
+    // Resource file / sidecar helpers apply with `chunkDir` as the collectionDir
+    // and the stringified index as the resourceId.
+    const chunkDir = this._chunkDir({ collectionDir, resourceId })
+    const chunkId = String(chunkIndex)
+    const filename = fileNameFor({
+      resourceId: chunkId,
+      contentType: input.contentType
+    })
+    const filePath = path.join(chunkDir, filename)
+    this._assertContained(filePath)
+
+    // Evaluate any precondition against the chunk's current version before
+    // writing (still inside the lock, so check and write are atomic).
+    if (ifMatch !== undefined || ifNoneMatch) {
+      await this._assertWritePrecondition({
+        collectionDir: chunkDir,
+        resourceId: chunkId,
+        ifMatch,
+        ifNoneMatch
+      })
+    }
+
+    // The chunk directory is created lazily on first write (a binary body is
+    // streamed into a temp file in it, so it must exist first).
+    await mkdir(chunkDir, { recursive: true })
+    await this._writeRepresentationBytes({ spaceId, filePath, input })
+
+    // A chunk has a single current representation: remove any prior one stored
+    // under a different content-type (write-new-then-prune).
+    const existing = await this._resourceFilesFor({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    await Promise.all(
+      existing
+        .filter(name => path.resolve(name) !== path.resolve(filePath))
+        .map(name => rm(name))
+    )
+
+    // Bump the chunk's monotonic `version` (its ETag validator), preserving its
+    // `createdAt`. A chunk carries no user Metadata / `createdBy` / epoch stamp.
+    const now = new Date().toISOString()
+    const prior = await this._readMetaSidecar({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    const version = (prior?.version ?? 0) + 1
+    await this._writeMetaSidecar({
+      collectionDir: chunkDir,
+      resourceId: chunkId,
+      sidecar: {
+        createdAt: prior?.createdAt ?? now,
+        updatedAt: now,
+        version
+      }
+    })
+    return { version }
+  }
+
+  /**
+   * Reads a chunk's bytes, resolving a `ResourceResult` (stream + resolved
+   * content-type + the chunk's `version`). Throws `ResourceNotFoundError` (404)
+   * 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<ResourceResult>}
+   */
+  async getChunk({
+    spaceId,
+    collectionId,
+    resourceId,
+    chunkIndex
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+  }): Promise<ResourceResult> {
+    const collectionDir = this._collectionDir({ spaceId, collectionId })
+    const chunkDir = this._chunkDir({ collectionDir, resourceId })
+    const chunkId = String(chunkIndex)
+    const filePath = await this._findFile({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    if (!filePath) {
+      throw new ResourceNotFoundError({ requestName: 'Get Chunk' })
+    }
+
+    try {
+      await fsStat(filePath)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new ResourceNotFoundError({ requestName: 'Get Chunk' })
+      }
+      throw err
+    }
+
+    const { contentType: storedResourceType } = parseResourceFileName(
+      path.basename(filePath)
+    )
+    const sidecar = await this._readMetaSidecar({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    return {
+      resourceStream: await openFileStream(filePath, this.logger),
+      storedResourceType,
+      ...(sidecar?.version !== undefined && { version: sidecar.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 collectionDir = this._collectionDir({ spaceId, collectionId })
+    const chunkDir = this._chunkDir({ collectionDir, resourceId })
+    const chunkId = String(chunkIndex)
+    const filePath = await this._findFile({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    if (!filePath) {
+      return undefined
+    }
+
+    let stats
+    try {
+      stats = await fsStat(filePath)
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return undefined
+      }
+      throw err
+    }
+
+    const { contentType } = parseResourceFileName(path.basename(filePath))
+    const sidecar = await this._readMetaSidecar({
+      collectionDir: chunkDir,
+      resourceId: chunkId
+    })
+    return {
+      contentType,
+      size: stats.size,
+      ...(sidecar?.version !== undefined && { version: sidecar.version })
+    }
+  }
+
+  /**
+   * Deletes one chunk (a hard delete: its bytes and version sidecar both go, and
+   * -- unlike a Resource -- it leaves no tombstone, since chunks are not part of
+   * the change feed). Resolves `true` when a chunk was removed and `false` when
+   * none was stored at that index. When `ifMatch` is supplied it is evaluated on
+   * the chunk's current version atomically with the removal (under the same
+   * per-Resource lock), throwing `PreconditionFailedError` (412) on a mismatch.
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param options.resourceId {string}
+   * @param options.chunkIndex {number}
+   * @param [options.ifMatch] {string}   `If-Match` precondition (a quoted ETag)
+   * @returns {Promise<boolean>}
+   */
+  async deleteChunk({
+    spaceId,
+    collectionId,
+    resourceId,
+    chunkIndex,
+    ifMatch
+  }: {
+    spaceId: string
+    collectionId: string
+    resourceId: string
+    chunkIndex: number
+    ifMatch?: string
+  }): Promise<boolean> {
+    const collectionDir = this._collectionDir({ spaceId, collectionId })
+    const chunkDir = this._chunkDir({ collectionDir, resourceId })
+    const chunkId = String(chunkIndex)
+    return this._writeMutex.run(
+      this._resourceLockKey({ spaceId, collectionId, resourceId }),
+      async () => {
+        const files = await this._resourceFilesFor({
+          collectionDir: chunkDir,
+          resourceId: chunkId
+        })
+        if (files.length === 0) {
+          // Absent: the handler 404s on `false` (chunk deletes are not silently
+          // idempotent, mirroring the EDV chunk contract).
+          return false
+        }
+        if (ifMatch !== undefined) {
+          await this._assertWritePrecondition({
+            collectionDir: chunkDir,
+            resourceId: chunkId,
+            ifMatch
+          })
+        }
+        await Promise.all(files.map(name => rm(name)))
+        // Remove the version sidecar too: a chunk keeps no tombstone.
+        await rm(
+          this._metaSidecarPath({
+            collectionDir: chunkDir,
+            resourceId: chunkId
+          }),
+          { force: true }
+        )
+        // When that was the last chunk, remove the now-empty chunk directory
+        // itself: a lingering empty `.chunks.<encId>/` would otherwise appear
+        // in the export walk (diverging from a Postgres export of the same
+        // logical state) and count its allocated block toward the du-based
+        // quota measurement. Safe under the per-Resource lock (`writeChunk`
+        // serializes on the same key, so nothing lands in the directory
+        // between the check and the rmdir).
+        const remaining = await fs.promises.readdir(chunkDir)
+        if (remaining.length === 0) {
+          await fs.promises.rmdir(chunkDir)
+        }
+        // Freed bytes: drop the cached quota usage so the next write re-measures.
+        this._usageCache.delete(spaceId)
+        return true
+      }
+    )
+  }
+
+  /**
+   * Lists a Resource's stored chunks in ascending `index` order -- the
+   * discovery/reassembly listing (the server never reassembles). Resolves an
+   * empty listing when the Resource has no chunk directory (including when the
+   * Resource itself is absent -- existence is the parent routes' concern).
+   * @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 collectionDir = this._collectionDir({ spaceId, collectionId })
+    const chunkDir = this._chunkDir({ collectionDir, resourceId })
+    let entries: fs.Dirent[]
+    try {
+      entries = await fs.promises.readdir(chunkDir, { withFileTypes: true })
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return { count: 0, chunks: [] }
+      }
+      throw err
+    }
+
+    // Keep only chunk representations (`r.<index>.<type>.<ext>`), dropping the
+    // `.meta.<index>.json` version sidecars.
+    const chunkEntries = entries.filter(
+      entry => entry.isFile() && entry.name.startsWith('r.')
+    )
+    const chunks = await Promise.all(
+      chunkEntries.map(async entry => {
+        const { resourceId: indexStr, contentType } = parseResourceFileName(
+          entry.name
+        )
+        const filePath = path.join(chunkDir, entry.name)
+        const stats = await fsStat(filePath)
+        const sidecar = await this._readMetaSidecar({
+          collectionDir: chunkDir,
+          resourceId: indexStr
+        })
+        return {
+          index: Number(indexStr),
+          size: stats.size,
+          contentType,
+          ...(sidecar?.version !== undefined && { version: sidecar.version })
+        }
+      })
+    )
+    chunks.sort((left, right) => left.index - right.index)
+    return { count: chunks.length, chunks }
+  }
+
   /**
    * Replication change feed (the `changes` query profile; see the
    * `StorageBackend.changesSince` contract.
@@ -2996,6 +3656,195 @@ export class FileSystemBackend implements StorageBackend {
     ).filter(candidate => candidate !== undefined)
   }
 
+  /**
+   * Plaintext equality query (the `equality` query profile; see the
+   * `StorageBackend.queryByEquality` contract). Reads every live Resource of
+   * the Collection -- JSON Resources carrying parsed `content`, blobs carrying
+   * only their sidecar `custom` -- and hands the candidates to the shared
+   * evaluator (`lib/equalityIndex.ts`) for extraction, matching, ordering, and
+   * cursor pagination. O(n) over the Collection per call, with every JSON body
+   * read -- deliberate for this teaching backend; a materialized backend would
+   * answer from an attribute index. Tombstones are excluded naturally (no live
+   * content file).
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param options.query {EqualityQuery}
+   * @param options.indexes {NormalizedIndexDeclaration[]}   the normalized
+   *   declared indexes (the request layer resolves them from the description)
+   * @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({
+      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({
+      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. Unlike `_readJsonCandidates` this INCLUDES blob Resources
+   * (a blob is queryable through its `custom`-sourced attributes): each entry
+   * resolves `{ resourceId, content?, custom? }`, where `content` is the parsed
+   * JSON of a JSON-typed representation (the blob content read is skipped, and
+   * unparsable JSON is dropped, as in `_readJsonCandidates`) and `custom` is the
+   * `.meta.` sidecar's `custom` when present. Tombstones are excluded naturally
+   * (no live `r.` content file); an optional excluded Resource is skipped. An
+   * absent Collection dir resolves empty.
+   * @param options {object}
+   * @param options.spaceId {string}
+   * @param options.collectionId {string}
+   * @param [options.excludeResourceId] {string}   omit this Resource (a conflict
+   *   scan excludes the Resource being written)
+   * @returns {Promise<EqualityCandidate[]>}
+   */
+  private async _readEqualityCandidates({
+    spaceId,
+    collectionId,
+    excludeResourceId
+  }: {
+    spaceId: string
+    collectionId: string
+    excludeResourceId?: string
+  }): Promise<EqualityCandidate[]> {
+    const collectionDir = this._collectionDir({ spaceId, collectionId })
+
+    let entries: fs.Dirent[] = []
+    try {
+      entries = await fs.promises.readdir(collectionDir, {
+        withFileTypes: true
+      })
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw err
+      }
+    }
+
+    return await Promise.all(
+      entries
+        .filter(entry => entry.isFile() && entry.name.startsWith('r.'))
+        .map(entry => ({
+          fileName: entry.name,
+          ...parseResourceFileName(entry.name)
+        }))
+        .filter(({ resourceId }) => resourceId !== excludeResourceId)
+        .map(async ({ resourceId, fileName, contentType }) => {
+          // Parse the content only for a JSON representation; a blob contributes
+          // no content-sourced attributes (its `custom` still makes it
+          // queryable). Unparsable JSON is treated as no content.
+          let content: unknown
+          if (isJson({ contentType })) {
+            try {
+              content = JSON.parse(
+                await fs.promises.readFile(
+                  path.join(collectionDir, fileName),
+                  'utf8'
+                )
+              ) as unknown
+            } catch {
+              content = undefined
+            }
+          }
+          const sidecar = await this._readMetaSidecar({
+            collectionDir,
+            resourceId
+          })
+          return {
+            resourceId,
+            ...(content !== undefined && { content }),
+            ...(sidecar?.custom !== undefined && { custom: sidecar.custom })
+          }
+        })
+    )
+  }
+
+  /**
+   * Reads and parses a single Resource's stored JSON content, or resolves
+   * `undefined` when the Resource is absent, a blob, or unparsable JSON -- the
+   * content side of a custom-sourced unique-attribute claim on a metadata write.
+   * @param options {object}
+   * @param options.collectionDir {string}
+   * @param options.resourceId {string}
+   * @returns {Promise<unknown>}
+   */
+  private async _readResourceJsonContent({
+    collectionDir,
+    resourceId
+  }: {
+    collectionDir: string
+    resourceId: string
+  }): Promise<unknown> {
+    const filePath = await this._findFile({ collectionDir, resourceId })
+    if (!filePath) {
+      return undefined
+    }
+    const { contentType } = parseResourceFileName(path.basename(filePath))
+    if (!isJson({ contentType })) {
+      return undefined
+    }
+    try {
+      return JSON.parse(await fs.promises.readFile(filePath, 'utf8')) as unknown
+    } catch {
+      return undefined
+    }
+  }
+
   // Policies
 
   /**