@peers-app/peers-sdk 0.30.0 → 0.30.2

package/dist/data/files/file-rows.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileIdFor = fileIdFor;
+exports.isLegacyFileId = isLegacyFileId;
+exports.isLegacyBundleFile = isLegacyBundleFile;
+exports.isRuntimeBundleFile = isRuntimeBundleFile;
+exports.isKeptFile = isKeptFile;
+exports.isCollectableFile = isCollectableFile;
+exports.isSameFile = isSameFile;
+exports.fileRowProblem = fileRowProblem;
+exports.checkFileWrite = checkFileWrite;
+/**
+ * The rules every `Files` row meets, on every device: ids derived from the content, rows that
+ * never change, and deletes only of runtime bundle rows. Each device checks an
+ * incoming row in full, so no member can put other content under a file's id.
+ */
+const derived_row_id_1 = require("../derived-row-id");
+const write_checks_1 = require("../orm/write-checks");
+const file_types_1 = require("./file.types");
+/** A chunk hash: SHA-256 as unpadded base64url. */
+const CHUNK_HASH = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * Names the package installer gives bundle files: `<packageId>-<kind>.bundle.js`, and the older
+ * `<name>.<kind>.<packageId>.js`.
+ */
+const BUNDLE_FILE_NAME = /^[0-9a-z]{25}-(package|routes|uis)\.bundle\.js$|^.+\.(package|routes|uis)\.[0-9a-z]{25}\.js$/;
+/**
+ * The id of a file: derived from its hash, size, name, MIME type and `keep`, so saving the same
+ * content with the same description gives the same file on every device. Give the name and MIME
+ * type as storage keeps them (`FileWriteStream` normalizes them), or other devices, which
+ * rederive the id from the stored row, refuse it.
+ *
+ * @param file - The file's hash, size, name, MIME type and `keep`.
+ */
+function fileIdFor(file) {
+    return (0, derived_row_id_1.derivedRowId)("Files", [
+        file.fileHash,
+        file.fileSize,
+        file.name,
+        file.mimeType ?? "",
+        file.keep,
+    ]);
+}
+/**
+ * Whether a row is a legacy file: one saved under a random id, before ids were derived from
+ * content. Legacy rows are admitted as they are, never change, and are always kept.
+ *
+ * @param fileId - The row's id.
+ */
+function isLegacyFileId(fileId) {
+    return !(0, derived_row_id_1.isDerivedRowId)(fileId);
+}
+/**
+ * Whether a legacy row is a package bundle the installer saved. The runtime owns these, so they
+ * are collected once nothing references them, and their rows may be deleted.
+ *
+ * @param file - The row's id and name.
+ */
+function isLegacyBundleFile(file) {
+    return isLegacyFileId(file.fileId) && BUNDLE_FILE_NAME.test(file.name);
+}
+/**
+ * Whether this is a runtime-owned package bundle: a legacy bundle, or a derived file with
+ * an installer bundle name, JavaScript MIME type and keep=false. Read keep through its
+ * identity when an older device relayed the row without that column.
+ */
+function isRuntimeBundleFile(file) {
+    return (isLegacyBundleFile(file) ||
+        (!isLegacyFileId(file.fileId) &&
+            BUNDLE_FILE_NAME.test(file.name) &&
+            file.mimeType === "application/javascript" &&
+            !isKeptFile(file)));
+}
+/**
+ * Whether a file is kept: never collected, even with nothing referencing it. A legacy row always
+ * is. A row relayed by a build that predates `keep` arrives without it; its id, derived from
+ * `keep`, then decides, and a row whose id says neither is kept.
+ *
+ * @param file - The row.
+ */
+function isKeptFile(file) {
+    if (isLegacyFileId(file.fileId))
+        return true;
+    if (typeof file.keep === "boolean")
+        return file.keep;
+    return fileIdFor({ ...file, keep: false }) !== file.fileId;
+}
+/** Whether an unreferenced file may expire, including the runtime's bundle exception. */
+function isCollectableFile(file) {
+    return isRuntimeBundleFile(file) || !isKeptFile(file);
+}
+/**
+ * Whether two rows describe the same file, ignoring how an older build stored it (no `keep`, no
+ * MIME type).
+ *
+ * @param a - One row.
+ * @param b - The other.
+ */
+function isSameFile(a, b) {
+    return (a.fileId === b.fileId &&
+        a.name === b.name &&
+        a.fileSize === b.fileSize &&
+        a.fileHash === b.fileHash &&
+        (a.mimeType ?? "") === (b.mimeType ?? "") &&
+        isKeptFile(a) === isKeptFile(b) &&
+        JSON.stringify(a.chunkHashes ?? []) === JSON.stringify(b.chunkHashes ?? []));
+}
+/**
+ * Why `file` can't be stored as a new row under `recordId`, or undefined when it can. A legacy
+ * row needs only a size within the limit. Any other must have its derived id, a chunk list of
+ * well-formed hashes, one per started MiB, and the `fileHash` of that list.
+ *
+ * @param file - The candidate row.
+ * @param recordId - The record id it's written under.
+ */
+function fileRowProblem(file, recordId) {
+    if (file.fileId !== recordId)
+        return "the row's id isn't its record id";
+    if (!Number.isSafeInteger(file.fileSize) || file.fileSize < 0) {
+        return "its size isn't a whole number of bytes";
+    }
+    if (file.fileSize > file_types_1.FILE_MAX_SIZE) {
+        return `it's over the ${file_types_1.FILE_MAX_SIZE / (1024 * 1024)} MiB limit`;
+    }
+    if (isLegacyFileId(file.fileId))
+        return undefined;
+    if (typeof file.name !== "string")
+        return "its name isn't text";
+    // Storage may return an absent value as null.
+    if (file.mimeType != null && typeof file.mimeType !== "string") {
+        return "its MIME type isn't text";
+    }
+    if (file.keep != null && typeof file.keep !== "boolean")
+        return "keep isn't a boolean";
+    const chunkHashes = file.chunkHashes ?? [];
+    if (!Array.isArray(chunkHashes) ||
+        !chunkHashes.every((hash) => typeof hash === "string" && CHUNK_HASH.test(hash))) {
+        return "its chunk list isn't a list of chunk hashes";
+    }
+    if (chunkHashes.length !== Math.ceil(file.fileSize / file_types_1.FILE_CHUNK_SIZE)) {
+        return "its chunk count doesn't match its size";
+    }
+    if (file.fileHash !== (0, file_types_1.fileHashOf)(chunkHashes))
+        return "its hash doesn't match its chunk list";
+    // A build that predates `keep` relays the row without it.
+    const keeps = typeof file.keep === "boolean" ? [file.keep] : [false, true];
+    if (!keeps.some((keep) => fileIdFor({ ...file, keep }) === file.fileId)) {
+        return "its id isn't derived from its content";
+    }
+    return undefined;
+}
+/**
+ * The `Files` write check: a new row must pass {@link fileRowProblem}; a stored row never
+ * changes (rewriting the same file is allowed); and only a stored runtime bundle row may be
+ * deleted. Unknown legacy ids remain allowed.
+ *
+ * @param existing - The row as stored, if any.
+ * @param candidate - The row to store, or undefined for a delete.
+ * @param recordId - The record written.
+ * @throws A {@link writeNotAuthorized} refusal.
+ */
+function checkFileWrite(existing, candidate, recordId) {
+    if (!candidate) {
+        if (existing ? isRuntimeBundleFile(existing) : isLegacyFileId(recordId))
+            return;
+        if (existing)
+            throw (0, write_checks_1.writeNotAuthorized)("Files", "a file can't be deleted");
+        // An unknown derived id carries no evidence that the row is a bundle. Refuse its delete
+        // so a later non-bundle row is still materialized from its authorized history. No later
+        // membership data changes that, so sync needn't keep the refusal for recovery.
+        throw (0, write_checks_1.writeRefusedForGood)("Files", "a file can't be deleted");
+    }
+    if (existing) {
+        if (!isSameFile(existing, candidate))
+            throw (0, write_checks_1.writeNotAuthorized)("Files", "a file can't change");
+        return;
+    }
+    const problem = fileRowProblem(candidate, recordId);
+    if (problem)
+        throw (0, write_checks_1.writeNotAuthorized)("Files", `the file is refused: ${problem}`);
+}
+(0, write_checks_1.registerTableWriteCheck)("Files", (existing, candidate, { recordId }) => checkFileWrite(existing, candidate, recordId));

package/dist/data/files/file-write-stream.d.ts

@@ -1,5 +1,9 @@
 import { type IFile, type IFileInput } from "./file.types";
 import type { FilesTable } from "./files";
+/**
+ * Writes one file in pieces: each full chunk is stored as it arrives, and `finalize` saves the
+ * row under the id derived from the content. Open one with {@link FilesTable.createWriteStream}.
+ */
 export declare class FileWriteStream {
     private metadata;
     private fileTable;
@@ -8,13 +12,36 @@ export declare class FileWriteStream {
     private bytesWritten;
     private finalized;
     private aborted;
+    /**
+     * @param metadata - The file's name, MIME type and `keep`.
+     * @param fileTable - The Files table the row is saved to.
+     */
     constructor(metadata: IFileInput, fileTable: FilesTable);
+    /**
+     * Append bytes. Full chunks are stored as they complete.
+     *
+     * @param chunk - The next bytes, of any length.
+     * @throws When the file would exceed {@link FILE_MAX_SIZE}, or the stream has ended.
+     */
     write(chunk: Uint8Array): Promise<void>;
     private processCompleteChunks;
+    private storeChunk;
+    /**
+     * Store the last chunk and save the file's row. Saving content that already has a row (the
+     * same bytes, name, MIME type and `keep`) returns the stored one; only a package bundle's row
+     * is written again, so a peer that deleted it gets it back.
+     *
+     * @returns The file's row.
+     */
     finalize(): Promise<IFile>;
+    /** Stop without saving a row. Stored chunks stay until collection frees them. */
     abort(): Promise<void>;
+    /** Bytes written so far. */
     getBytesWritten(): number;
+    /** Chunks stored so far. */
     getChunkCount(): number;
+    /** Whether `finalize` has saved the row. */
     isFinalized(): boolean;
+    /** Whether `abort` was called. */
     isAborted(): boolean;
 }

package/dist/data/files/file-write-stream.js

@@ -2,7 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileWriteStream = void 0;
 const keys_1 = require("../../keys");
+const chunk_store_1 = require("./chunk-store");
 const file_types_1 = require("./file.types");
+const file_rows_1 = require("./file-rows");
+/**
+ * `text` as every host's storage keeps it. The id must be derived from the text as stored, or no
+ * other device could rederive it. A lone surrogate (possible in a Windows file name) becomes
+ * U+FFFD. The PWA's sql.js also cuts text at a NUL and drops a leading U+FEFF when reading, so
+ * neither is kept anywhere.
+ */
+function asStored(text) {
+    if (typeof text !== "string")
+        return text;
+    // ignoreBOM leaves U+FEFF for the replace, which drops every leading one (sql.js drops one).
+    const wellFormed = new TextDecoder("utf-8", { ignoreBOM: true }).decode(new TextEncoder().encode(text));
+    return wellFormed.split("\0", 1)[0].replace(/^\uFEFF+/, "");
+}
+/**
+ * Writes one file in pieces: each full chunk is stored as it arrives, and `finalize` saves the
+ * row under the id derived from the content. Open one with {@link FilesTable.createWriteStream}.
+ */
 class FileWriteStream {
     metadata;
     fileTable;
@@ -11,10 +30,20 @@ class FileWriteStream {
     bytesWritten = 0;
     finalized = false;
     aborted = false;
+    /**
+     * @param metadata - The file's name, MIME type and `keep`.
+     * @param fileTable - The Files table the row is saved to.
+     */
     constructor(metadata, fileTable) {
         this.metadata = metadata;
         this.fileTable = fileTable;
     }
+    /**
+     * Append bytes. Full chunks are stored as they complete.
+     *
+     * @param chunk - The next bytes, of any length.
+     * @throws When the file would exceed {@link FILE_MAX_SIZE}, or the stream has ended.
+     */
     async write(chunk) {
         if (this.finalized) {
             throw new Error("Cannot write to finalized stream");
@@ -22,6 +51,9 @@ class FileWriteStream {
         if (this.aborted) {
             throw new Error("Cannot write to aborted stream");
         }
+        if (this.bytesWritten + chunk.length > file_types_1.FILE_MAX_SIZE) {
+            throw new Error(`A file can be at most ${file_types_1.FILE_MAX_SIZE / (1024 * 1024)} MiB`);
+        }
         // Add chunk to buffer
         this.buffer = new Uint8Array(Buffer.concat([this.buffer, chunk]));
         this.bytesWritten += chunk.length;
@@ -29,18 +61,26 @@ class FileWriteStream {
         await this.processCompleteChunks();
     }
     async processCompleteChunks() {
-        const ops = await (0, file_types_1.getFileOps)();
         while (this.buffer.length >= file_types_1.FILE_CHUNK_SIZE) {
-            // Extract one chunk
             const chunkData = this.buffer.subarray(0, file_types_1.FILE_CHUNK_SIZE);
             this.buffer = this.buffer.subarray(file_types_1.FILE_CHUNK_SIZE);
-            // Hash and store the chunk
-            const chunkHash = (0, keys_1.hashBytes)(chunkData);
-            this.chunkHashes.push(chunkHash);
-            const chunkPath = `${file_types_1.CHUNKS_DIR}/${chunkHash}`;
-            await ops.writeFile(chunkPath, chunkData);
+            await this.storeChunk(chunkData);
         }
     }
+    async storeChunk(chunkData) {
+        const chunkHash = (0, keys_1.hashBytes)(chunkData);
+        this.chunkHashes.push(chunkHash);
+        // Stored even when present: a save restores bytes a device has freed, and refreshes the
+        // chunk's age so a sweep can't free it under this save.
+        await (await (0, chunk_store_1.getChunkStore)()).put(chunkHash, chunkData);
+    }
+    /**
+     * Store the last chunk and save the file's row. Saving content that already has a row (the
+     * same bytes, name, MIME type and `keep`) returns the stored one; only a package bundle's row
+     * is written again, so a peer that deleted it gets it back.
+     *
+     * @returns The file's row.
+     */
     async finalize() {
         if (this.finalized) {
             throw new Error("Stream already finalized");
@@ -48,45 +88,28 @@ class FileWriteStream {
         if (this.aborted) {
             throw new Error("Cannot finalize aborted stream");
         }
-        // First, process any complete chunks in the buffer
         await this.processCompleteChunks();
-        // Then process any remaining partial data as final chunk
         if (this.buffer.length > 0) {
-            const ops = await (0, file_types_1.getFileOps)();
-            const finalChunkHash = (0, keys_1.hashBytes)(this.buffer);
-            this.chunkHashes.push(finalChunkHash);
-            const chunkPath = `${file_types_1.CHUNKS_DIR}/${finalChunkHash}`;
-            await ops.writeFile(chunkPath, this.buffer);
+            await this.storeChunk(this.buffer);
             this.buffer = new Uint8Array(0);
         }
-        // Create the file record using the same logic as FileTable.saveFile
-        const chunkHashesString = JSON.stringify(this.chunkHashes);
-        const fileHash = (0, keys_1.hashBytes)(Buffer.from(chunkHashesString, "utf8"));
-        let fileRecord;
-        if (this.chunkHashes.length > file_types_1.CHUNK_INDEX_THRESHOLD) {
-            // Large file: use recursive index file
-            const indexFileId = await this.fileTable.createIndexFileRecursively(this.chunkHashes);
-            fileRecord = {
-                ...this.metadata,
-                fileSize: this.bytesWritten,
-                fileHash,
-                indexFileId,
-            };
-        }
-        else {
-            // Small file: store chunk hashes directly
-            fileRecord = {
-                ...this.metadata,
-                fileSize: this.bytesWritten,
-                fileHash,
-                chunkHashes: this.chunkHashes,
-            };
-        }
-        // Save to database
-        await this.fileTable.saveFileRecord(fileRecord);
+        const description = {
+            name: asStored(this.metadata.name),
+            fileSize: this.bytesWritten,
+            fileHash: (0, file_types_1.fileHashOf)(this.chunkHashes),
+            mimeType: asStored(this.metadata.mimeType ?? ""),
+            keep: this.metadata.keep ?? true,
+        };
+        const fileRecord = {
+            fileId: (0, file_rows_1.fileIdFor)(description),
+            ...description,
+            chunkHashes: this.chunkHashes,
+        };
+        const saved = await this.fileTable.saveFileRecord(fileRecord);
         this.finalized = true;
-        return fileRecord;
+        return saved;
     }
+    /** Stop without saving a row. Stored chunks stay until collection frees them. */
     async abort() {
         if (this.finalized) {
             throw new Error("Cannot abort finalized stream");
@@ -94,18 +117,20 @@ class FileWriteStream {
         this.aborted = true;
         this.buffer = Buffer.alloc(0);
         this.chunkHashes = [];
-        // Note: We don't delete chunks since they may be shared with other files
-        // Chunk cleanup should be handled by a separate garbage collection process
     }
+    /** Bytes written so far. */
     getBytesWritten() {
         return this.bytesWritten;
     }
+    /** Chunks stored so far. */
     getChunkCount() {
         return this.chunkHashes.length;
     }
+    /** Whether `finalize` has saved the row. */
     isFinalized() {
         return this.finalized;
     }
+    /** Whether `abort` was called. */
     isAborted() {
         return this.aborted;
     }

package/dist/data/files/file.types.d.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
 import { type ITableMetaData } from "../orm/types";
+/**
+ * A `Files` row: one file's description and its chunk list. Rows saved since ids became derived
+ * from content have a `000r` id and never change; older rows ("legacy") have random ids.
+ */
 export declare const fileSchema: z.ZodObject<{
     fileId: z.ZodEffects<z.ZodString, string, string>;
     name: z.ZodString;
@@ -7,47 +11,79 @@ export declare const fileSchema: z.ZodObject<{
     fileHash: z.ZodString;
     mimeType: z.ZodOptional<z.ZodString>;
     chunkHashes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    isIndexFile: z.ZodOptional<z.ZodBoolean>;
-    indexFileId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    keep: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     fileId: string;
     fileSize: number;
     fileHash: string;
+    keep?: boolean | undefined;
     mimeType?: string | undefined;
     chunkHashes?: string[] | undefined;
-    isIndexFile?: boolean | undefined;
-    indexFileId?: string | undefined;
 }, {
     name: string;
     fileId: string;
     fileSize: number;
     fileHash: string;
+    keep?: boolean | undefined;
     mimeType?: string | undefined;
     chunkHashes?: string[] | undefined;
-    isIndexFile?: boolean | undefined;
-    indexFileId?: string | undefined;
 }>;
+/** A `Files` row. */
 export type IFile = z.infer<typeof fileSchema>;
-export type IFileInput = Pick<IFile, "fileId" | "name" | "fileSize" | "mimeType" | "isIndexFile">;
+/**
+ * What a writer chooses about a new file. The id is derived from the content and these, so
+ * saving the same bytes with the same name, MIME type and `keep` returns the same file.
+ */
+export interface IFileInput {
+    /**
+     * Stored as every host can keep it: a lone surrogate becomes U+FFFD, the text ends at a NUL,
+     * and a leading U+FEFF is dropped. The saved row has the name as stored.
+     */
+    name: string;
+    /** Stored like `name`; an omitted MIME type is stored empty. */
+    mimeType?: string;
+    /**
+     * Whether the file is never collected. Defaults to true, so a writer that doesn't declare its
+     * references keeps its files. System Files saves and the package installer pass false.
+     */
+    keep?: boolean;
+}
+/** The `Files` system table: every context has one. */
 export declare const filesMetaData: ITableMetaData;
+/** Size of each chunk a file is split into; the last chunk may be shorter. */
 export declare const FILE_CHUNK_SIZE: number;
-export declare const CHUNKS_DIR = "file_chunks";
-export declare let CHUNK_INDEX_THRESHOLD: number;
-export declare function setChunkIndexThreshold(threshold: number): void;
+/** Most chunks one file may have: a row's chunk list holds every chunk of any file. */
+export declare const FILE_MAX_CHUNKS = 1024;
+/** Largest file Peers stores (1 GiB). It can rise in a later release, never fall. */
+export declare const FILE_MAX_SIZE: number;
+/** Most chunks a read fetches from other devices at once, so a large file isn't one stream. */
+export declare const FILE_FETCH_WINDOW = 16;
+/** Default time an unreferenced file is retained, before the grace period (30 days). */
+export declare const FILE_RETENTION_MS: number;
+/** Extra time for a reference to reach devices holding the bytes (7 days). */
+export declare const FILE_COLLECTION_GRACE_MS: number;
+/** Minimum age of a stored chunk before collection (one day, longer than a write session). */
+export declare const FILE_CHUNK_FLOOR_MS: number;
 /**
- * Compute the file-system hash for content without saving it.
- * Mirrors the chunking + hashing logic of FileWriteStream so the result
- * matches `IFile.fileHash` for the same bytes.
+ * Collection delays. `PEERS_FILE_COLLECTION_DELAY_MS` overrides all three for tests only;
+ * absent or invalid uses the constants. Explicit group retention is unaffected.
+ */
+export declare function fileCollectionDelays(): {
+    retentionMs: number;
+    graceMs: number;
+    chunkFloorMs: number;
+};
+/**
+ * A file's `fileHash`: the SHA-256 of its chunk hashes as JSON, in order.
+ *
+ * @param chunkHashes - The file's chunk hashes.
+ */
+export declare function fileHashOf(chunkHashes: readonly string[]): string;
+/**
+ * Compute the file-system hash for content without saving it. Mirrors the chunking of
+ * `FileWriteStream`, so the result matches `IFile.fileHash` for the same bytes.
+ *
+ * @param content - The bytes, or a string hashed as UTF-8.
  */
 export declare function computeFileHash(content: string | Uint8Array): string;
-export interface FileOps {
-    downloadFileChunk(chunkHash: string): Promise<Uint8Array | null>;
-    fileExists(path: string): Promise<boolean>;
-    readFile(path: string): Promise<Uint8Array>;
-    writeFile(path: string, data: Uint8Array): Promise<void>;
-    deletePath(path: string): Promise<void>;
-}
-export declare function setFileOps(ops: FileOps): void;
-export declare function getFileOps(): Promise<FileOps>;
-export declare function resetFileOps(): void;

package/dist/data/files/file.types.js

@@ -1,80 +1,83 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHUNK_INDEX_THRESHOLD = exports.CHUNKS_DIR = exports.FILE_CHUNK_SIZE = exports.filesMetaData = exports.fileSchema = void 0;
-exports.setChunkIndexThreshold = setChunkIndexThreshold;
+exports.FILE_CHUNK_FLOOR_MS = exports.FILE_COLLECTION_GRACE_MS = exports.FILE_RETENTION_MS = exports.FILE_FETCH_WINDOW = exports.FILE_MAX_SIZE = exports.FILE_MAX_CHUNKS = exports.FILE_CHUNK_SIZE = exports.filesMetaData = exports.fileSchema = void 0;
+exports.fileCollectionDelays = fileCollectionDelays;
+exports.fileHashOf = fileHashOf;
 exports.computeFileHash = computeFileHash;
-exports.setFileOps = setFileOps;
-exports.getFileOps = getFileOps;
-exports.resetFileOps = resetFileOps;
 const zod_1 = require("zod");
 const keys_1 = require("../../keys");
 const zod_types_1 = require("../../types/zod-types");
 const types_1 = require("../orm/types");
+/**
+ * A `Files` row: one file's description and its chunk list. Rows saved since ids became derived
+ * from content have a `000r` id and never change; older rows ("legacy") have random ids.
+ */
 exports.fileSchema = zod_1.z.object({
     fileId: zod_types_1.zodPeerId,
     name: zod_1.z.string().describe("The name of the file"),
     fileSize: zod_1.z.number().describe("The size of the file in bytes"),
     fileHash: zod_1.z.string().describe("Hash of the chunk hashes array for integrity verification"),
-    mimeType: zod_1.z.string().optional().describe("The MIME type of the file"),
-    chunkHashes: zod_1.z
-        .array(zod_1.z.string())
-        .optional()
-        .describe("SHA-256 hashes of each chunk in order (for small files)"),
-    isIndexFile: zod_1.z
+    mimeType: zod_1.z.string().optional().describe("The MIME type of the file; empty when unknown"),
+    chunkHashes: zod_1.z.array(zod_1.z.string()).optional().describe("SHA-256 hashes of each chunk in order"),
+    keep: zod_1.z
         .boolean()
         .optional()
-        .describe("True if this is an index file for another large file"),
-    indexFileId: zod_types_1.zodPeerId.optional().describe("FileId of index file (for large files)"),
+        .describe("True for a file that is never collected, even with nothing referencing it"),
 });
+/** The `Files` system table: every context has one. */
 exports.filesMetaData = {
     name: "Files",
     description: "Files stored in the chunked file system for peer sharing",
     primaryKeyName: "fileId",
     fields: (0, types_1.schemaToFields)(exports.fileSchema),
 };
-// File storage configuration
-exports.FILE_CHUNK_SIZE = 1024 * 1024; // 1MB chunks
-exports.CHUNKS_DIR = "file_chunks";
-exports.CHUNK_INDEX_THRESHOLD = 1000; // Use chunk index file for files with >1000 chunks (~1GB)
-// For testing - allow modifying the threshold
-function setChunkIndexThreshold(threshold) {
-    exports.CHUNK_INDEX_THRESHOLD = threshold;
+/** Size of each chunk a file is split into; the last chunk may be shorter. */
+exports.FILE_CHUNK_SIZE = 1024 * 1024;
+/** Most chunks one file may have: a row's chunk list holds every chunk of any file. */
+exports.FILE_MAX_CHUNKS = 1024;
+/** Largest file Peers stores (1 GiB). It can rise in a later release, never fall. */
+exports.FILE_MAX_SIZE = exports.FILE_MAX_CHUNKS * exports.FILE_CHUNK_SIZE;
+/** Most chunks a read fetches from other devices at once, so a large file isn't one stream. */
+exports.FILE_FETCH_WINDOW = 16;
+/** Default time an unreferenced file is retained, before the grace period (30 days). */
+exports.FILE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+/** Extra time for a reference to reach devices holding the bytes (7 days). */
+exports.FILE_COLLECTION_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Minimum age of a stored chunk before collection (one day, longer than a write session). */
+exports.FILE_CHUNK_FLOOR_MS = 24 * 60 * 60 * 1000;
+/**
+ * Collection delays. `PEERS_FILE_COLLECTION_DELAY_MS` overrides all three for tests only;
+ * absent or invalid uses the constants. Explicit group retention is unaffected.
+ */
+function fileCollectionDelays() {
+    const value = typeof process === "undefined" ? undefined : process.env.PEERS_FILE_COLLECTION_DELAY_MS;
+    const override = value === undefined || value.trim() === "" ? NaN : Number(value);
+    const delay = (fallback) => Number.isFinite(override) && override >= 0 ? override : fallback;
+    return {
+        retentionMs: delay(exports.FILE_RETENTION_MS),
+        graceMs: delay(exports.FILE_COLLECTION_GRACE_MS),
+        chunkFloorMs: delay(exports.FILE_CHUNK_FLOOR_MS),
+    };
 }
 /**
- * Compute the file-system hash for content without saving it.
- * Mirrors the chunking + hashing logic of FileWriteStream so the result
- * matches `IFile.fileHash` for the same bytes.
+ * A file's `fileHash`: the SHA-256 of its chunk hashes as JSON, in order.
+ *
+ * @param chunkHashes - The file's chunk hashes.
+ */
+function fileHashOf(chunkHashes) {
+    return (0, keys_1.hashBytes)(new TextEncoder().encode(JSON.stringify(chunkHashes)));
+}
+/**
+ * Compute the file-system hash for content without saving it. Mirrors the chunking of
+ * `FileWriteStream`, so the result matches `IFile.fileHash` for the same bytes.
+ *
+ * @param content - The bytes, or a string hashed as UTF-8.
  */
 function computeFileHash(content) {
     const data = typeof content === "string" ? new Uint8Array(Buffer.from(content, "utf8")) : content;
     const chunkHashes = [];
-    let offset = 0;
-    while (offset < data.length) {
-        const end = Math.min(offset + exports.FILE_CHUNK_SIZE, data.length);
-        chunkHashes.push((0, keys_1.hashBytes)(data.subarray(offset, end)));
-        offset = end;
-    }
-    return (0, keys_1.hashBytes)(new Uint8Array(Buffer.from(JSON.stringify(chunkHashes), "utf8")));
-}
-let fileOps = null;
-let fileOpsReady = null;
-function setFileOps(ops) {
-    fileOps = ops;
-    if (fileOpsReady) {
-        fileOpsReady(ops);
-        fileOpsReady = null; // Reset the promise if it was waiting
+    for (let offset = 0; offset < data.length; offset += exports.FILE_CHUNK_SIZE) {
+        chunkHashes.push((0, keys_1.hashBytes)(data.subarray(offset, offset + exports.FILE_CHUNK_SIZE)));
     }
-}
-function getFileOps() {
-    if (fileOps) {
-        return Promise.resolve(fileOps);
-    }
-    return new Promise((resolve) => {
-        fileOpsReady = resolve;
-    });
-}
-// For testing - reset the global state
-function resetFileOps() {
-    fileOps = null;
-    fileOpsReady = null;
+    return fileHashOf(chunkHashes);
 }