@peers-app/peers-sdk 0.29.2 → 0.30.1

package/dist/contracts/contract-resolvers.js

@@ -211,6 +211,7 @@ async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
 }
 const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}${reason ? ` (${reason})` : ""}`);
 const localOnlyContractIds = new Set([
+    system_ids_1.fileStorageContractId,
     system_ids_1.filesContractId,
     system_ids_1.groupMembersContractId,
     system_ids_1.hostToolsContractId,

package/dist/contracts/index.d.ts

@@ -19,6 +19,7 @@ export * from "./system/app-updates-contract";
 export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractDefinitionWithPolicy, type IContractProviderInfo, type IContractToolPolicy, type IExposedContractInfo, type IExposedToolInfo, type IGetContractDefinitionInput, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
 export * from "./system/desktop-tools-contract";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
+export * from "./system/file-storage-contract";
 export * from "./system/files-contract";
 export * from "./system/group-members-contract";
 export * from "./system/host-shell-contract";

package/dist/contracts/index.js

@@ -105,6 +105,7 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+__exportStar(require("./system/file-storage-contract"), exports);
 __exportStar(require("./system/files-contract"), exports);
 __exportStar(require("./system/group-members-contract"), exports);
 __exportStar(require("./system/host-shell-contract"), exports);

package/dist/contracts/system/file-storage-contract.d.ts

@@ -0,0 +1,76 @@
+import type { IChunkStoreStats } from "../../data/files/chunk-store";
+import type { IContractDefinition } from "../types";
+/** Version of the local-only System File Storage contract. */
+export declare const FILE_STORAGE_CONTRACT_VERSION = 1;
+/** What one migration of legacy chunks into the account's chunk store found and did. */
+export interface IChunkMigrationResult {
+    /** Whether every chunk the account's files list, that the legacy store had, is now stored. */
+    verified: boolean;
+    /** Why it stopped before copying: rows it can't migrate, or contexts it can't read or index. */
+    problems: string[];
+    /** Contexts read: the personal one and every group, disabled ones included. */
+    contexts: number;
+    /** Files rows read. */
+    files: number;
+    /** Distinct chunks those rows list, less the skipped ones. */
+    needed: number;
+    /** Chunks only orphaned legacy bundle rows list, which aren't copied. */
+    skippedBundleChunks: number;
+    /** Needed chunks the store already had. */
+    alreadyStored: number;
+    /** Needed chunks copied from the legacy store. */
+    copied: number;
+    /** Needed chunks the legacy store didn't have: this device never had them. */
+    missing: number;
+    /** Needed chunks the legacy store held with the wrong bytes (a write cut short). */
+    corrupt: number;
+    /** When it started, by this device's clock. */
+    startedAt: number;
+    /** When it finished, by this device's clock. */
+    finishedAt: number;
+}
+/**
+ * Where a migration stands: `not-needed` when the device has no legacy store (or it's removed),
+ * `pending` before the first run, then `running`, `blocked` (see the result's problems) or
+ * `verified`.
+ */
+export type ChunkMigrationState = "not-needed" | "pending" | "running" | "blocked" | "verified";
+/** This device's chunk storage for the signed-in account. */
+export interface IFileStorageStatus {
+    /** The account's chunk store. */
+    store: IChunkStoreStats;
+    /** The legacy store, while it exists. */
+    legacy?: {
+        /** Where it is, such as the folder's path. */
+        location: string;
+        /** Accounts on this device whose migration is verified. */
+        migratedAccounts: string[];
+        /** Accounts on this device still to migrate; it can be removed once none are left. */
+        waitingAccounts: string[];
+    };
+    /** The migration of the legacy store. */
+    migration: {
+        state: ChunkMigrationState;
+        /** The last run this session, if any. */
+        lastRun?: IChunkMigrationResult;
+    };
+}
+/** The tools of System File Storage v1. */
+export interface IFileStorageConsumer {
+    tools: {
+        /** The chunk store's size, the legacy store, and where the migration stands. */
+        getStatus(): Promise<IFileStorageStatus>;
+        /** Copy this account's chunks out of the legacy store now, and verify them. */
+        migrate(): Promise<IChunkMigrationResult>;
+        /** Copy again, then delete the legacy store once every account on the device has migrated. */
+        removeLegacyChunks(): Promise<{
+            removed: boolean;
+            location?: string;
+        }>;
+    };
+}
+/**
+ * Return the System File Storage v1 declaration: this device's chunk store and the migration
+ * of its legacy chunks. Only the user's own screens and CLI on this device may call it.
+ */
+export declare function getFileStorageContractDefinition(): IContractDefinition;

package/dist/contracts/system/file-storage-contract.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_STORAGE_CONTRACT_VERSION = void 0;
+exports.getFileStorageContractDefinition = getFileStorageContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+/** Version of the local-only System File Storage contract. */
+exports.FILE_STORAGE_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const migrationResultFields = [
+    field("verified", field_type_1.FieldType.boolean, "Whether every chunk the legacy store had is now stored."),
+    field("problems", field_type_1.FieldType.any, "Why it stopped before copying, if it did."),
+    field("contexts", field_type_1.FieldType.number, "Contexts read."),
+    field("files", field_type_1.FieldType.number, "Files rows read."),
+    field("needed", field_type_1.FieldType.number, "Distinct chunks the rows list, less skipped ones."),
+    field("skippedBundleChunks", field_type_1.FieldType.number, "Chunks only orphaned bundle rows list."),
+    field("alreadyStored", field_type_1.FieldType.number, "Needed chunks already stored."),
+    field("copied", field_type_1.FieldType.number, "Needed chunks copied."),
+    field("missing", field_type_1.FieldType.number, "Needed chunks this device never had."),
+    field("corrupt", field_type_1.FieldType.number, "Needed chunks stored with the wrong bytes."),
+    field("startedAt", field_type_1.FieldType.number, "When it started."),
+    field("finishedAt", field_type_1.FieldType.number, "When it finished."),
+];
+/**
+ * Return the System File Storage v1 declaration: this device's chunk store and the migration
+ * of its legacy chunks. Only the user's own screens and CLI on this device may call it.
+ */
+function getFileStorageContractDefinition() {
+    return {
+        contractId: system_ids_1.fileStorageContractId,
+        version: exports.FILE_STORAGE_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System File Storage",
+        description: "This device's chunk store and the migration of its legacy chunks.",
+        tables: [],
+        observables: [],
+        events: [],
+        tools: [
+            {
+                name: "getStatus",
+                usageDescription: "Report the chunk store's size and the legacy migration's state.",
+                inputFields: [],
+                outputFields: [
+                    field("store", field_type_1.FieldType.object, "Chunks stored and their total bytes."),
+                    field("legacy", field_type_1.FieldType.object, "The legacy store, while it exists.", {
+                        optional: true,
+                    }),
+                    field("migration", field_type_1.FieldType.object, "The migration's state and last run."),
+                ],
+            },
+            {
+                name: "migrate",
+                usageDescription: "Copy the account's chunks from the legacy store, and verify them.",
+                inputFields: [],
+                outputFields: migrationResultFields,
+            },
+            {
+                name: "removeLegacyChunks",
+                usageDescription: "Delete the legacy chunk store once every account on this device has migrated.",
+                inputFields: [],
+                outputFields: [
+                    field("removed", field_type_1.FieldType.boolean, "False when there was nothing to remove."),
+                    field("location", field_type_1.FieldType.string, "Where it was.", { optional: true }),
+                ],
+            },
+        ],
+    };
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.fileStorageContractId,
+    version: exports.FILE_STORAGE_CONTRACT_VERSION,
+    getDefinition: getFileStorageContractDefinition,
+});

package/dist/contracts/system/files-contract.d.ts

@@ -2,5 +2,9 @@ import type { IContractDefinition } from "../types";
 export * from "./files-shared";
 /** Version of the local-only System Files contract. */
 export declare const FILES_CONTRACT_VERSION = 1;
-/** Return the System Files v1 declaration. Tool identities are derived by the catalog. */
+/**
+ * Return the System Files v1 declaration: `save` and `read`, and a write session (`startSave`,
+ * `appendSave`, `finishSave`, `cancelSave`) for files over one call. Tool identities are derived
+ * by the catalog.
+ */
 export declare function getFilesContractDefinition(): IContractDefinition;

package/dist/contracts/system/files-contract.js

@@ -24,9 +24,22 @@ __exportStar(require("./files-shared"), exports);
 /** Version of the local-only System Files contract. */
 exports.FILES_CONTRACT_VERSION = 1;
 const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
-/** Return the System Files v1 declaration. Tool identities are derived by the catalog. */
+/**
+ * Return the System Files v1 declaration: `save` and `read`, and a write session (`startSave`,
+ * `appendSave`, `finishSave`, `cancelSave`) for files over one call. Tool identities are derived
+ * by the catalog.
+ */
 function getFilesContractDefinition() {
     const size = `${files_shared_1.FILES_MAX_CALL_BYTES / (1024 * 1024)} MiB`;
+    const maxFile = `${files_shared_1.FILES_MAX_FILE_BYTES / (1024 * 1024 * 1024)} GiB`;
+    const sessionField = field("sessionId", field_type_1.FieldType.id, "The write session, from startSave.");
+    const savedFields = [
+        field("fileId", field_type_1.FieldType.id, "Id to read the file with."),
+        field("name", field_type_1.FieldType.string, "File name."),
+        field("fileSize", field_type_1.FieldType.number, "Size in bytes."),
+        field("fileHash", field_type_1.FieldType.string, "Hash of the file's chunk hashes."),
+        field("mimeType", field_type_1.FieldType.string, "MIME type.", { optional: true }),
+    ];
     return {
         contractId: system_ids_1.filesContractId,
         version: exports.FILES_CONTRACT_VERSION,
@@ -39,7 +52,7 @@ function getFilesContractDefinition() {
         tools: [
             {
                 name: "save",
-                usageDescription: `Save a new file of up to ${size} in this context and return its id.`,
+                usageDescription: `Save a file of up to ${size} in this context and return its id.`,
                 inputFields: [
                     field("name", field_type_1.FieldType.string, "File name, such as avatar.jpg."),
                     field("mimeType", field_type_1.FieldType.string, "MIME type, such as image/jpeg.", {
@@ -47,13 +60,7 @@ function getFilesContractDefinition() {
                     }),
                     field("bytes", field_type_1.FieldType.blob, `The whole file, at most ${size}.`),
                 ],
-                outputFields: [
-                    field("fileId", field_type_1.FieldType.id, "Id to read the file with."),
-                    field("name", field_type_1.FieldType.string, "File name."),
-                    field("fileSize", field_type_1.FieldType.number, "Size in bytes."),
-                    field("fileHash", field_type_1.FieldType.string, "Hash of the file's chunk hashes."),
-                    field("mimeType", field_type_1.FieldType.string, "MIME type.", { optional: true }),
-                ],
+                outputFields: savedFields,
             },
             {
                 name: "read",
@@ -74,6 +81,40 @@ function getFilesContractDefinition() {
                     field("mimeType", field_type_1.FieldType.string, "MIME type.", { optional: true }),
                 ],
             },
+            {
+                name: "startSave",
+                usageDescription: `Start saving a file over ${size}, of up to ${maxFile}, in pieces.`,
+                inputFields: [
+                    field("name", field_type_1.FieldType.string, "File name, such as video.mp4."),
+                    field("mimeType", field_type_1.FieldType.string, "MIME type, such as video/mp4.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [sessionField],
+            },
+            {
+                name: "appendSave",
+                usageDescription: `Add the next piece, of up to ${size}, to a file being saved.`,
+                inputFields: [
+                    sessionField,
+                    field("bytes", field_type_1.FieldType.blob, `The next bytes, at most ${size}.`),
+                ],
+                outputFields: [field("bytesWritten", field_type_1.FieldType.number, "Bytes saved so far.")],
+            },
+            {
+                name: "finishSave",
+                usageDescription: "Finish saving a file and return its id.",
+                inputFields: [sessionField],
+                outputFields: savedFields,
+            },
+            {
+                name: "cancelSave",
+                usageDescription: "Stop saving a file; nothing is saved.",
+                inputFields: [sessionField],
+                outputFields: [
+                    field("cancelled", field_type_1.FieldType.boolean, "False when the session had already ended."),
+                ],
+            },
         ],
     };
 }

package/dist/contracts/system/files-shared.d.ts

@@ -1,6 +1,13 @@
 import type { IContractConsumerBase } from "../contract-proxy";
-/** Largest file `save` accepts, and the most bytes one `read` returns. */
+/** Largest file `save` accepts, the most bytes one `appendSave` takes, and one `read` returns. */
 export declare const FILES_MAX_CALL_BYTES: number;
+/** Largest file Peers stores (1 GiB). Save one over {@link FILES_MAX_CALL_BYTES} in pieces. */
+export declare const FILES_MAX_FILE_BYTES: number;
+/**
+ * Largest file {@link readWholeFile} reads unless told otherwise (64 MiB), so a screen doesn't
+ * hold a large file in memory. Read a larger file, such as a video, in ranges.
+ */
+export declare const FILES_WHOLE_READ_MAX_BYTES: number;
 /** Input for {@link IFilesConsumer tools.save}. */
 export interface IFilesSaveInput {
     /** File name, such as `avatar.jpg`. Shown to people; not a path. */
@@ -19,6 +26,22 @@ export interface IFilesSaveResult {
     fileHash: string;
     mimeType?: string;
 }
+/** Input for {@link IFilesConsumer tools.startSave}: the file's name and MIME type. */
+export type IFilesStartSaveInput = Omit<IFilesSaveInput, "bytes">;
+/** A write session, for {@link IFilesConsumer tools.appendSave} and `finishSave`. */
+export interface IFilesSaveSession {
+    sessionId: string;
+}
+/** Input for {@link IFilesConsumer tools.appendSave}. */
+export interface IFilesAppendSaveInput extends IFilesSaveSession {
+    /** The next bytes, at most {@link FILES_MAX_CALL_BYTES}. */
+    bytes: Uint8Array;
+}
+/** What {@link IFilesConsumer tools.appendSave} returns. */
+export interface IFilesAppendSaveResult {
+    /** Bytes the session holds so far. */
+    bytesWritten: number;
+}
 /** Input for {@link IFilesConsumer tools.read}. */
 export interface IFilesReadInput {
     fileId: string;
@@ -42,18 +65,60 @@ export interface IFilesReadResult {
 /**
  * Consumer shape for System Files: save and read files in the caller's own data context.
  * Files sync to the context's other devices, as every file does.
+ *
+ * A file over {@link FILES_MAX_CALL_BYTES} is saved in a write session: `startSave`, then
+ * `appendSave` for each piece in order, then `finishSave`. {@link saveWholeFile} does that. A
+ * session ends after 10 minutes without a call, or 12 hours after it started; `cancelSave` ends
+ * one early.
  */
 export interface IFilesConsumer extends IContractConsumerBase {
     tools: {
         save(input: IFilesSaveInput): Promise<IFilesSaveResult>;
         read(input: IFilesReadInput): Promise<IFilesReadResult>;
+        startSave(input: IFilesStartSaveInput): Promise<IFilesSaveSession>;
+        appendSave(input: IFilesAppendSaveInput): Promise<IFilesAppendSaveResult>;
+        finishSave(input: IFilesSaveSession): Promise<IFilesSaveResult>;
+        cancelSave(input: IFilesSaveSession): Promise<{
+            cancelled: boolean;
+        }>;
     };
 }
 /**
- * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}.
+ * What {@link saveWholeFile} saves from: bytes, or anything that reads in slices like a browser
+ * `Blob` or `File`, so a large file needn't be in memory all at once.
+ */
+export type FileBytesSource = Uint8Array | {
+    size: number;
+    slice(start: number, end: number): {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    };
+};
+/**
+ * Save a file of up to {@link FILES_MAX_FILE_BYTES} through System Files: one `save` when it
+ * fits in one call, otherwise a write session in pieces of {@link FILES_MAX_CALL_BYTES}. A
+ * session that fails is cancelled.
+ *
+ * ```ts
+ * const { fileId } = await saveWholeFile(files.tools, { name: file.name, mimeType: file.type, bytes: file });
+ * ```
+ *
+ * @param tools - The consumer's tools, from a package, a screen or the host.
+ * @param input - Name, optional MIME type, and the bytes or a `Blob`.
+ * @returns The saved file's description.
+ */
+export declare function saveWholeFile(tools: Pick<IFilesConsumer["tools"], "save" | "startSave" | "appendSave" | "finishSave" | "cancelSave">, input: Omit<IFilesSaveInput, "bytes"> & {
+    bytes: FileBytesSource;
+}): Promise<IFilesSaveResult>;
+/**
+ * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}. It refuses
+ * a file over `maxBytes`, so a large file isn't read into memory by mistake: read a video, say,
+ * in ranges instead.
  *
  * @param read - The consumer's `read` tool, from a package, a screen or the host.
  * @param fileId - File to read.
+ * @param opts.maxBytes - Largest file to read; {@link FILES_WHOLE_READ_MAX_BYTES} by default.
  * @returns The file's bytes, name and MIME type.
  */
-export declare function readWholeFile(read: IFilesConsumer["tools"]["read"], fileId: string): Promise<IFilesReadResult>;
+export declare function readWholeFile(read: IFilesConsumer["tools"]["read"], fileId: string, opts?: {
+    maxBytes?: number;
+}): Promise<IFilesReadResult>;

package/dist/contracts/system/files-shared.js

@@ -1,20 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FILES_MAX_CALL_BYTES = void 0;
+exports.FILES_WHOLE_READ_MAX_BYTES = exports.FILES_MAX_FILE_BYTES = exports.FILES_MAX_CALL_BYTES = void 0;
+exports.saveWholeFile = saveWholeFile;
 exports.readWholeFile = readWholeFile;
-// System Files' limits, shapes and read helper, without the contract's registration, so package
+// System Files' limits, shapes and helpers, without the contract's registration, so package
 // code can import them from `@peers-app/peers-sdk/define`.
-/** Largest file `save` accepts, and the most bytes one `read` returns. */
+/** Largest file `save` accepts, the most bytes one `appendSave` takes, and one `read` returns. */
 exports.FILES_MAX_CALL_BYTES = 8 * 1024 * 1024;
+/** Largest file Peers stores (1 GiB). Save one over {@link FILES_MAX_CALL_BYTES} in pieces. */
+exports.FILES_MAX_FILE_BYTES = 1024 * 1024 * 1024;
 /**
- * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}.
+ * Largest file {@link readWholeFile} reads unless told otherwise (64 MiB), so a screen doesn't
+ * hold a large file in memory. Read a larger file, such as a video, in ranges.
+ */
+exports.FILES_WHOLE_READ_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Save a file of up to {@link FILES_MAX_FILE_BYTES} through System Files: one `save` when it
+ * fits in one call, otherwise a write session in pieces of {@link FILES_MAX_CALL_BYTES}. A
+ * session that fails is cancelled.
+ *
+ * ```ts
+ * const { fileId } = await saveWholeFile(files.tools, { name: file.name, mimeType: file.type, bytes: file });
+ * ```
+ *
+ * @param tools - The consumer's tools, from a package, a screen or the host.
+ * @param input - Name, optional MIME type, and the bytes or a `Blob`.
+ * @returns The saved file's description.
+ */
+async function saveWholeFile(tools, input) {
+    const { bytes: source, ...description } = input;
+    // Make a local view too: direct host tools validate with `instanceof Uint8Array`.
+    const bytes = ArrayBuffer.isView(source) && Object.prototype.toString.call(source) === "[object Uint8Array]"
+        ? new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
+        : undefined;
+    const blob = source;
+    if (!bytes &&
+        (!blob || typeof blob.slice !== "function" || !Number.isSafeInteger(blob.size) || blob.size < 0)) {
+        throw new Error("System Files: bytes must be a Uint8Array or a Blob-like source");
+    }
+    const size = bytes ? bytes.length : blob.size;
+    const piece = async (start, end) => bytes ? bytes.subarray(start, end) : new Uint8Array(await blob.slice(start, end).arrayBuffer());
+    if (size <= exports.FILES_MAX_CALL_BYTES) {
+        return tools.save({ ...description, bytes: await piece(0, size) });
+    }
+    if (size > exports.FILES_MAX_FILE_BYTES) {
+        throw new Error(`System Files: a file can be at most ${exports.FILES_MAX_FILE_BYTES / 1024 ** 2} MiB`);
+    }
+    const { sessionId } = await tools.startSave(description);
+    try {
+        for (let start = 0; start < size; start += exports.FILES_MAX_CALL_BYTES) {
+            const end = Math.min(size, start + exports.FILES_MAX_CALL_BYTES);
+            await tools.appendSave({ sessionId, bytes: await piece(start, end) });
+        }
+        return await tools.finishSave({ sessionId });
+    }
+    catch (error) {
+        await tools.cancelSave({ sessionId }).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}. It refuses
+ * a file over `maxBytes`, so a large file isn't read into memory by mistake: read a video, say,
+ * in ranges instead.
  *
  * @param read - The consumer's `read` tool, from a package, a screen or the host.
  * @param fileId - File to read.
+ * @param opts.maxBytes - Largest file to read; {@link FILES_WHOLE_READ_MAX_BYTES} by default.
  * @returns The file's bytes, name and MIME type.
  */
-async function readWholeFile(read, fileId) {
+async function readWholeFile(read, fileId, opts) {
+    const maxBytes = opts?.maxBytes ?? exports.FILES_WHOLE_READ_MAX_BYTES;
     const first = await read({ fileId, length: exports.FILES_MAX_CALL_BYTES });
+    if (first.fileSize > maxBytes) {
+        throw new Error(`File ${fileId} is ${first.fileSize} bytes, over readWholeFile's limit of ${maxBytes} bytes; read it in ranges`);
+    }
     if (first.bytes.length >= first.fileSize)
         return first;
     const bytes = new Uint8Array(first.fileSize);

package/dist/contracts/validate.d.ts

@@ -3,6 +3,7 @@ import type { IAlsoImplementsDeclaration, IContractDefinition, IValidationResult
  * Validate that an implementation contract satisfies a target contract shape.
  * The implementation must be a superset: all contract tables, tools,
  * observables, and events must be present with compatible shapes.
+ * A table field that keeps files in the target must keep them in the implementation too.
  */
 export declare function validateProviderSatisfiesContract(impl: IContractDefinition, contract: IContractDefinition): IValidationResult;
 /**

package/dist/contracts/validate.js

@@ -5,6 +5,7 @@ exports.contractShapeChanges = contractShapeChanges;
 exports.validateImmutability = validateImmutability;
 exports.validateAlsoImplements = validateAlsoImplements;
 const lodash_1 = require("lodash");
+const field_type_1 = require("../types/field-type");
 const types_1 = require("./types");
 function ok() {
     return { valid: true, errors: [] };
@@ -56,7 +57,10 @@ function validateTableFields(contractTable, implTable) {
             }
             continue;
         }
-        const compat = isFieldCompatible(contractField, implField, "both");
+        const compat = isFieldCompatible(contractField, implField, "both") ??
+            ((0, field_type_1.isFileReferenceField)(contractField) && !(0, field_type_1.isFileReferenceField)(implField)
+                ? "contract requires a file reference, implementation does not declare one"
+                : null);
         if (compat) {
             errors.push({
                 kind: "field",
@@ -150,6 +154,7 @@ function validateEventFields(contractEvent, implEvent) {
  * Validate that an implementation contract satisfies a target contract shape.
  * The implementation must be a superset: all contract tables, tools,
  * observables, and events must be present with compatible shapes.
+ * A table field that keeps files in the target must keep them in the implementation too.
  */
 function validateProviderSatisfiesContract(impl, contract) {
     const errors = [];

package/dist/data/derived-row-id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Leading characters of every derived row id. Every derived prefix starts `000`, while `newid()`
+ * ids start with their creation time, so the two can't collide.
+ */
+export declare const DERIVED_ROW_ID_PREFIX = "000r";
+/** A value a derived row id is computed from. */
+export type DerivedRowValue = string | number | boolean;
+/**
+ * The id of a row derived from its values: a hash of `["row/1", tableName, values]` as JSON,
+ * after {@link DERIVED_ROW_ID_PREFIX}. The encoding is frozen: ids derived this way are stored
+ * on every device, so changing it would orphan them.
+ *
+ * The hash part is 21 base-36 characters (about 108 bits). Taking over an existing id needs a
+ * second preimage (about 2^108 work); crafting two rows with one id costs about 2^54.
+ *
+ * @param tableName - The table's name.
+ * @param values - The values the id is derived from, in a fixed order.
+ * @throws When a value isn't a string, a finite number or a boolean.
+ */
+export declare function derivedRowId(tableName: string, values: readonly DerivedRowValue[]): string;
+/**
+ * Whether `id` has the form of a {@link derivedRowId}: a hint, not a proof that it was derived.
+ *
+ * @param id - A candidate row id.
+ */
+export declare function isDerivedRowId(id: unknown): boolean;

package/dist/data/derived-row-id.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DERIVED_ROW_ID_PREFIX = void 0;
+exports.derivedRowId = derivedRowId;
+exports.isDerivedRowId = isDerivedRowId;
+/**
+ * Row ids derived from a row's own values, the same on every device. `Files` is the first user;
+ * a later `defineTable({ idFrom })` declaration derives its ids the same way, so no id changes.
+ *
+ * Kept free of heavy imports, like `signed-row-id.ts`, so package code can compute them.
+ */
+const peer_id_1 = require("../peer-id");
+/**
+ * Leading characters of every derived row id. Every derived prefix starts `000`, while `newid()`
+ * ids start with their creation time, so the two can't collide.
+ */
+exports.DERIVED_ROW_ID_PREFIX = "000r";
+/**
+ * The id of a row derived from its values: a hash of `["row/1", tableName, values]` as JSON,
+ * after {@link DERIVED_ROW_ID_PREFIX}. The encoding is frozen: ids derived this way are stored
+ * on every device, so changing it would orphan them.
+ *
+ * The hash part is 21 base-36 characters (about 108 bits). Taking over an existing id needs a
+ * second preimage (about 2^108 work); crafting two rows with one id costs about 2^54.
+ *
+ * @param tableName - The table's name.
+ * @param values - The values the id is derived from, in a fixed order.
+ * @throws When a value isn't a string, a finite number or a boolean.
+ */
+function derivedRowId(tableName, values) {
+    for (const value of values) {
+        if (typeof value !== "string" &&
+            typeof value !== "boolean" &&
+            !(typeof value === "number" && Number.isFinite(value))) {
+            throw new Error(`Table ${tableName}: a derived id's values must be strings, numbers or booleans`);
+        }
+    }
+    return (0, peer_id_1.deterministicPeerId)(exports.DERIVED_ROW_ID_PREFIX, JSON.stringify(["row/1", tableName, values]));
+}
+/**
+ * Whether `id` has the form of a {@link derivedRowId}: a hint, not a proof that it was derived.
+ *
+ * @param id - A candidate row id.
+ */
+function isDerivedRowId(id) {
+    return typeof id === "string" && id.length === 25 && id.startsWith(exports.DERIVED_ROW_ID_PREFIX);
+}