@peers-app/peers-sdk 0.25.9 → 0.25.10

package/dist/contracts/__tests__/contract-proxy.test.js

@@ -426,6 +426,32 @@ describe("contract proxy — error handling", () => {
         const consumer = consumerVia(contract, provider);
         await expect(consumer.tables.Widgets.list()).rejects.toThrow(/does not provide table 'Widgets'/);
     });
+    it("forwards callerPackageId when the resolution opts into call context", async () => {
+        const seen = [];
+        const provider = (0, contract_proxy_1.createContractProvider)({
+            contractId: CONTRACT_ID,
+            version: 1,
+            forwardCallContext: true,
+            tools: {
+                listGrants: {
+                    tool: { toolId: (0, utils_1.newid)(), name: "listGrants", accessLevel: 0 },
+                    toolFn: async (host) => {
+                        seen.push(host.callerPackageId ?? null);
+                        return "ok";
+                    },
+                },
+            },
+        });
+        await provider({
+            contractId: CONTRACT_ID,
+            version: 1,
+            member: "tool",
+            name: "listGrants",
+            operation: "run",
+            args: [],
+        }, { callerPackageId: "00pkg00000000000000000001" });
+        expect(seen).toEqual(["00pkg00000000000000000001"]);
+    });
     it.each([
         ["tool", "missingTool"],
         ["observable", "missingObservable"],
@@ -520,6 +546,52 @@ describe("contract proxy — permission checks", () => {
         expect(denied.table.save).not.toHaveBeenCalled();
     });
 });
+describe("contract provider endpoint event filter", () => {
+    it("delivers a generic event only to subscribers the filter allows", async () => {
+        const handlers = new Set();
+        const changed = {
+            eventName: () => "changed",
+            subscribe: (handler) => {
+                handlers.add(handler);
+                return {
+                    unsubscribe: () => {
+                        handlers.delete(handler);
+                        return true;
+                    },
+                };
+            },
+        };
+        const resolution = {
+            contractId: CONTRACT_ID,
+            version: 1,
+            events: { changed: changed },
+            eventFilter: (_eventName, payload, context) => payload.owner === context.callerPackageId,
+        };
+        const delivered = [];
+        const endpoint = (0, contract_proxy_1.createContractProviderEndpoint)(resolution, {
+            notify: async (notification) => {
+                delivered.push(notification.subscriptionId);
+            },
+        });
+        const subscribe = (subscriptionId, callerPackageId) => endpoint.handleCall({
+            contractId: CONTRACT_ID,
+            version: 1,
+            member: "event",
+            name: "changed",
+            operation: "subscribe",
+            subscriptionId,
+            args: [],
+        }, { callerPackageId });
+        await subscribe("allowed", "pkg-a");
+        await subscribe("denied", "pkg-b");
+        for (const handler of handlers) {
+            handler({ owner: "pkg-a" });
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+        expect(delivered).toEqual(["allowed"]);
+        endpoint.dispose();
+    });
+});
 describe("connectionContractTransport", () => {
     it("emits on the request channel with the call and returns the response", async () => {
         const emit = jest.fn(async (_event, _call) => ["ok"]);

package/dist/contracts/contract-proxy.d.ts

@@ -220,6 +220,11 @@ export interface IContractToolContext {
      * by the host and returned only to the provider-side tool implementation.
      */
     getVariable(variableName: string, requestingToolId: string): Promise<string>;
+    /**
+     * Isolated package that originated this call, when the host runtime supplied one.
+     * Absent for trusted local callers (the signed-in UI session and the CLI).
+     */
+    callerPackageId?: string;
 }
 /**
  * Build the **consumer** side of a contract proxy from a contract definition and a
@@ -293,6 +298,13 @@ export interface IContractResolution {
      * Omit this for remote or otherwise untrusted provider routes.
      */
     toolContext?: IContractToolContext;
+    /**
+     * When true, provider tool functions receive an {@link IContractToolContext} as their
+     * final argument even if {@link toolContext} was not set, including
+     * {@link IContractToolContext.callerPackageId} from the current call. Host contracts
+     * that authorize by calling package set this.
+     */
+    forwardCallContext?: boolean;
     observables?: Record<string, Observable<any>>;
     /**
      * Provider-owned write policy for live observables. A `set` is allowed only when the
@@ -306,6 +318,20 @@ export interface IContractResolution {
      * their payloads to its configured notification sink.
      */
     events?: Record<string, Event<any>>;
+    /**
+     * Optional per-subscriber gate for generic contract events.
+     *
+     * Table and observable streams are not filtered. The endpoint invokes this once
+     * per subscriber with the {@link IContractCallContext} captured at subscribe time.
+     * Return false, or reject, to drop that notification for that subscriber only.
+     * A shared endpoint can therefore hide one caller's events from another.
+     *
+     * @param eventName Contract event name, such as `changed`.
+     * @param payload Payload about to be delivered.
+     * @param context Caller identity from the subscribe call.
+     * @returns Whether this subscriber may receive the payload.
+     */
+    eventFilter?: (eventName: string, payload: unknown, context: IContractCallContext) => boolean | Promise<boolean>;
 }
 /** Identity of the caller, supplied by the transport layer for permission checks. */
 export interface IContractCallContext {
@@ -319,6 +345,11 @@ export interface IContractCallContext {
      * host router before dispatch.
      */
     callerDeviceId?: string;
+    /**
+     * Isolated package that originated this call. Set by the isolate runtime from host
+     * state, never from a guest payload. Absent for trusted local UI and CLI callers.
+     */
+    callerPackageId?: string;
     /**
      * Provider-side data context used to resolve the caller's group/personal role.
      * In-process only — never serialized across a connection.
@@ -418,7 +449,9 @@ export interface IContractProviderEndpoint {
  * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
  * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
  * fanned out through the supplied {@link ContractNotificationSink} as an
- * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * {@link IContractNotification}. Generic events pass through
+ * {@link IContractResolution.eventFilter} once per subscriber, using the caller context
+ * captured when that subscriber subscribed. The endpoint owns no request listener, which lets a
  * connection-wide router multiplex many endpoints through one request channel and later
  * substitute sandbox-backed endpoint implementations.
  *

package/dist/contracts/contract-proxy.js

@@ -534,9 +534,19 @@ function createContractProvider(resolution, opts = {}) {
                     throw new Error(`Contract ${call.contractId} does not provide tool '${call.name}'`);
                 }
                 await assertContractToolAccess(tool, call, context);
-                return resolution.toolContext
-                    ? tool.toolFn(...call.args, resolution.toolContext)
-                    : tool.toolFn(...call.args);
+                if (resolution.toolContext || resolution.forwardCallContext) {
+                    const base = resolution.toolContext ?? {
+                        dataContextId: context.dataContext?.dataContextId ?? "",
+                        getVariable: async () => {
+                            throw new Error("Persistent variables are not available to this contract tool");
+                        },
+                    };
+                    return tool.toolFn(...call.args, {
+                        ...base,
+                        callerPackageId: context.callerPackageId,
+                    });
+                }
+                return tool.toolFn(...call.args);
             }
             case "observable": {
                 const obs = resolution.observables?.[call.name];
@@ -571,7 +581,9 @@ function createContractProvider(resolution, opts = {}) {
  * or an {@link Observable} (`resolution.observables[name]`) — is only subscribed to while at
  * least one consumer holds a subscription (refcounted by a resolved key), and each payload is
  * fanned out through the supplied {@link ContractNotificationSink} as an
- * {@link IContractNotification}. The endpoint owns no request listener, which lets a
+ * {@link IContractNotification}. Generic events pass through
+ * {@link IContractResolution.eventFilter} once per subscriber, using the caller context
+ * captured when that subscriber subscribed. The endpoint owns no request listener, which lets a
  * connection-wide router multiplex many endpoints through one request channel and later
  * substitute sandbox-backed endpoint implementations.
  *
@@ -581,9 +593,10 @@ function createContractProvider(resolution, opts = {}) {
 function createContractProviderEndpoint(resolution, opts) {
     const { notify, permissionCheck, context: defaultContext } = opts;
     const dispatch = createContractProvider(resolution, { permissionCheck });
-    // One live subscription per resolved subscription key, refcounted by the set of
-    // consumer subscription ids currently attached to it, plus a reverse index for
-    // unsubscribe. Keys namespace generic events (`event:<name>`), table events
+    // One live subscription per resolved subscription key, refcounted by the subscribers
+    // currently attached to it, plus a reverse index for unsubscribe. Each subscriber keeps
+    // the caller context from its subscribe call so event filters can differ per consumer.
+    // Keys namespace generic events (`event:<name>`), table events
     // (`table:<name>:<event>`), and observable streams (`observable:<name>`) so the same
     // machinery serves all three.
     const byKey = new Map();
@@ -651,29 +664,51 @@ function createContractProviderEndpoint(resolution, opts) {
             },
         };
     };
-    const subscribe = (key, attach, subscriptionId) => {
+    const reportNotifyFailure = (subscriptionId, err) => {
+        console.error(`Contract notify failed for subscription '${subscriptionId}'`, err);
+    };
+    const deliver = (key, subscriptionId, payload, context) => {
+        // Start each notification independently. A slow or rejected destination must not
+        // block sibling subscribers, and every rejection is handled because Observable
+        // callbacks do not await returned promises. Without a filter, attach the catch
+        // directly so a rejected notify is logged on the same turn as before.
+        if (!(key.startsWith("event:") && resolution.eventFilter)) {
+            if (!subIdToKey.has(subscriptionId)) {
+                return;
+            }
+            void notifySink(subscriptionId, payload, key).catch((err) => {
+                reportNotifyFailure(subscriptionId, err);
+            });
+            return;
+        }
+        void (async () => {
+            const allowed = await resolution.eventFilter?.(key.slice("event:".length), payload, context);
+            if (!allowed || !subIdToKey.has(subscriptionId)) {
+                return;
+            }
+            await notifySink(subscriptionId, payload, key);
+        })().catch((err) => {
+            reportNotifyFailure(subscriptionId, err);
+        });
+    };
+    const subscribe = (key, attach, subscriptionId, context) => {
         if (subIdToKey.has(subscriptionId)) {
             throw new Error(`Duplicate contract subscriptionId '${subscriptionId}'`);
         }
         let entry = byKey.get(key);
         if (!entry) {
             // First subscriber for this key: attach the single live subscription.
-            const subIds = new Set();
+            const subscribers = new Map();
             const detach = attach((payload) => {
-                // Start each notification independently. A slow or rejected destination must not
-                // block sibling subscribers, and every rejection is handled because Observable
-                // callbacks do not await returned promises.
-                for (const sid of [...subIds]) {
-                    void notifySink(sid, payload, key).catch((err) => {
-                        console.error(`Contract notify failed for subscription '${sid}'`, err);
-                    });
+                for (const [sid, subscriberContext] of [...subscribers]) {
+                    deliver(key, sid, payload, subscriberContext);
                 }
             });
-            entry = { liveUnsub: detach, subIds };
+            entry = { liveUnsub: detach, subscribers };
             byKey.set(key, entry);
         }
         subIdToKey.set(subscriptionId, key);
-        entry.subIds.add(subscriptionId);
+        entry.subscribers.set(subscriptionId, context);
     };
     const unsubscribe = (subscriptionId) => {
         const key = subIdToKey.get(subscriptionId);
@@ -685,8 +720,8 @@ function createContractProviderEndpoint(resolution, opts) {
         if (!entry) {
             return;
         }
-        entry.subIds.delete(subscriptionId);
-        if (entry.subIds.size === 0) {
+        entry.subscribers.delete(subscriptionId);
+        if (entry.subscribers.size === 0) {
             // Last subscriber left: detach the live subscription (nothing more is pushed).
             entry.liveUnsub();
             byKey.delete(key);
@@ -731,7 +766,7 @@ function createContractProviderEndpoint(resolution, opts) {
                     throw new Error(`Contract provider endpoint ${resolution.contractId} v${resolution.version} is disposed`);
                 }
                 const { key, attach } = resolveSubscription(call);
-                subscribe(key, attach, call.subscriptionId);
+                subscribe(key, attach, call.subscriptionId, context);
             }
             finally {
                 pendingSubIds.delete(call.subscriptionId);

package/dist/contracts/contract-resolvers.js

@@ -149,6 +149,7 @@ const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.
 const localOnlyContractIds = new Set([
     system_ids_1.identityContractId,
     system_ids_1.invitesContractId,
+    system_ids_1.localFoldersContractId,
     system_ids_1.toolAccessControlContractId,
 ]);
 /**

package/dist/contracts/index.d.ts

@@ -15,6 +15,7 @@ export { createRemoteContractEndpoint, getRemoteContractTransportFactory, type I
 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 { getIdentityContractDefinition, IDENTITY_CONTRACT_VERSION, type IIdentityConsumer, type IIdentitySessionInfo, } from "./system/identity-contract";
 export { getInvitesContractDefinition, type IAcceptInviteResult, type ICreatedInvite, type IInvitePreview, type IInvitesConsumer, INVITES_CONTRACT_VERSION, } from "./system/invites-contract";
+export { getLocalFoldersContractDefinition, type ILocalFolderChange, type ILocalFolderChangedEvent, type ILocalFolderEntry, type ILocalFolderFileBlocks, type ILocalFolderFileBlocksInput, type ILocalFolderGrantInfo, type ILocalFolderIndexInput, type ILocalFolderJobFinishedEvent, type ILocalFolderJobHandle, type ILocalFolderJobInfo, type ILocalFolderJobProgressEvent, type ILocalFolderListInput, type ILocalFolderMoveInput, type ILocalFolderPathInput, type ILocalFolderPurgeTrashInput, type ILocalFolderReadRangeInput, type ILocalFolderReadRangeResult, type ILocalFolderRequestGrantInput, type ILocalFolderStatInput, LOCAL_FOLDERS_CHUNK_AVG, LOCAL_FOLDERS_CHUNK_MAX, LOCAL_FOLDERS_CHUNK_MIN, LOCAL_FOLDERS_CONTRACT_VERSION, LOCAL_FOLDERS_JOB_TTL_MS, LOCAL_FOLDERS_READ_RANGE_MAX, LOCAL_FOLDERS_RESERVED_DIR, type LocalFolderChangeKind, type LocalFolderEntryKind, type LocalFolderMode, localFoldersProviderPackageId, } from "./system/local-folders-contract";
 export { getLogsContractDefinition, type ILogsConsumer, LOGS_CONTRACT_VERSION, resolveLogsContract, } from "./system/logs-contract";
 export * from "./system/network-contracts";
 export { getToolAccessControlContractDefinition, type IToolAccessControlConsumer, TOOL_ACCESS_CONTROL_CONTRACT_VERSION, } from "./system/tool-access-control-contract";

package/dist/contracts/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEVICE_OPERATIONS_MAX_ROWS = exports.DEVICE_OPERATIONS_MAX_RESULT_BYTES = exports.DEVICE_OPERATIONS_MAX_QUERY_LENGTH = exports.DEVICE_OPERATIONS_CONTRACT_VERSION = exports.setRemoteContractTransportFactory = exports.resolveRemoteTargetEndpoint = exports.getRemoteContractTransportFactory = exports.createRemoteContractEndpoint = exports.ContractRegistry = exports.PersistentContractRegistry = exports.waitForHostContractTransport = exports.subscribeHostContractTransport = exports.registerHostContractTransport = exports.getHostContractTransport = exports.hostContractConsumer = exports.setSchemaToFieldsFn = exports.extractToolShape = exports.extractTableShape = exports.createLocalContractConsumer = exports.contractsSchema = exports.contractsMetaData = exports.ContractsTable = exports.Contracts = exports.inProcessTransportPair = exports.connectionContractTransport = exports.CONTRACT_REQUEST_CHANNEL = exports.CONTRACT_NOTIFY_CHANNEL = exports.verifyRemoteContractIdentity = exports.registerContractResolver = exports.isSelfTrustedContractCaller = exports.handleContractCall = exports.getContractResolver = exports.createUserContextContractProviderRouter = exports.createLocalUserContextContractProviderRouter = exports.authorizeRemoteContractCall = exports.sameUserContractPermissionCheck = exports.createRemoteContractConsumer = exports.createContractProviderSession = exports.createContractProviderEndpoint = exports.createContractProvider = exports.createContractConsumer = exports.CONTRACT_CALL_RPC = exports.contractProvidersSchema = exports.contractProvidersMetaData = exports.ContractProvidersTable = exports.ContractProviders = exports.createContractProviderRouter = exports.PackageBuilder = exports.definePackage = exports.ContractBuilder = void 0;
-exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = void 0;
+exports.validateProviderSatisfiesContract = exports.validateImmutability = exports.validateAlsoImplements = exports.contractKey = exports.registerSystemContract = exports.listSystemContracts = exports.installSystemContracts = exports.TOOL_ACCESS_CONTROL_CONTRACT_VERSION = exports.getToolAccessControlContractDefinition = exports.resolveLogsContract = exports.LOGS_CONTRACT_VERSION = exports.getLogsContractDefinition = exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_CONTRACT_VERSION = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.getLocalFoldersContractDefinition = exports.INVITES_CONTRACT_VERSION = exports.getInvitesContractDefinition = exports.IDENTITY_CONTRACT_VERSION = exports.getIdentityContractDefinition = exports.getDeviceOperationsContractDefinition = exports.deviceOperationsToolIds = exports.deviceOperationsProviderPackageId = exports.DEVICE_OPERATIONS_MAX_TOOLS = void 0;
 var builder_1 = require("./builder");
 Object.defineProperty(exports, "ContractBuilder", { enumerable: true, get: function () { return builder_1.ContractBuilder; } });
 Object.defineProperty(exports, "definePackage", { enumerable: true, get: function () { return builder_1.definePackage; } });
@@ -91,6 +91,16 @@ Object.defineProperty(exports, "IDENTITY_CONTRACT_VERSION", { enumerable: true,
 var invites_contract_1 = require("./system/invites-contract");
 Object.defineProperty(exports, "getInvitesContractDefinition", { enumerable: true, get: function () { return invites_contract_1.getInvitesContractDefinition; } });
 Object.defineProperty(exports, "INVITES_CONTRACT_VERSION", { enumerable: true, get: function () { return invites_contract_1.INVITES_CONTRACT_VERSION; } });
+var local_folders_contract_1 = require("./system/local-folders-contract");
+Object.defineProperty(exports, "getLocalFoldersContractDefinition", { enumerable: true, get: function () { return local_folders_contract_1.getLocalFoldersContractDefinition; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_AVG", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_AVG; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_MAX", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_MAX; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CHUNK_MIN", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CHUNK_MIN; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_CONTRACT_VERSION", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_CONTRACT_VERSION; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_JOB_TTL_MS", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_JOB_TTL_MS; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_READ_RANGE_MAX", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_READ_RANGE_MAX; } });
+Object.defineProperty(exports, "LOCAL_FOLDERS_RESERVED_DIR", { enumerable: true, get: function () { return local_folders_contract_1.LOCAL_FOLDERS_RESERVED_DIR; } });
+Object.defineProperty(exports, "localFoldersProviderPackageId", { enumerable: true, get: function () { return local_folders_contract_1.localFoldersProviderPackageId; } });
 var logs_contract_1 = require("./system/logs-contract");
 Object.defineProperty(exports, "getLogsContractDefinition", { enumerable: true, get: function () { return logs_contract_1.getLogsContractDefinition; } });
 Object.defineProperty(exports, "LOGS_CONTRACT_VERSION", { enumerable: true, get: function () { return logs_contract_1.LOGS_CONTRACT_VERSION; } });

package/dist/contracts/system/local-folders-contract.d.ts

@@ -0,0 +1,163 @@
+import type { IContractDefinition } from "../types";
+/** Version of the built-in System Local Folders contract. */
+export declare const LOCAL_FOLDERS_CONTRACT_VERSION = 1;
+/** Maximum byte length accepted by `readRange` in one call. */
+export declare const LOCAL_FOLDERS_READ_RANGE_MAX: number;
+/** FastCDC minimum block size. Files at or below this size are one block. */
+export declare const LOCAL_FOLDERS_CHUNK_MIN: number;
+/** FastCDC target average block size. */
+export declare const LOCAL_FOLDERS_CHUNK_AVG: number;
+/** FastCDC maximum block size. */
+export declare const LOCAL_FOLDERS_CHUNK_MAX: number;
+/** Directory name reserved inside every grant for trash and in-flight files. */
+export declare const LOCAL_FOLDERS_RESERVED_DIR = ".peers";
+/** How long finished index jobs stay readable via `getJob`. */
+export declare const LOCAL_FOLDERS_JOB_TTL_MS: number;
+/** Package ID used by live System Local Folders tool instances. */
+export declare const localFoldersProviderPackageId = "000peers0system0000000001";
+/** Grant mode accepted by `requestGrant`. */
+export type LocalFolderMode = "read" | "readwrite";
+/** Filesystem entry kind returned by `list` and `stat`. */
+export type LocalFolderEntryKind = "file" | "dir" | "symlink";
+/** Watcher change kind delivered on the `changed` event. */
+export type LocalFolderChangeKind = "created" | "modified" | "deleted" | "renamed";
+/** Input for {@link ILocalFoldersConsumer tools.requestGrant}. */
+export interface ILocalFolderRequestGrantInput {
+    groupId: string;
+    mode: LocalFolderMode;
+    /** Operator-only. Ignored when an isolated package is the caller. */
+    packageId?: string;
+    /**
+     * Operator-only absolute path. Isolated callers cannot set this.
+     * Omit it on a desktop host to open the folder picker.
+     */
+    absolutePath?: string;
+}
+/** One active grant returned by `requestGrant` and `listGrants`. */
+export interface ILocalFolderGrantInfo {
+    grantId: string;
+    groupId: string;
+    absolutePath: string;
+    mode: LocalFolderMode;
+    packageId?: string;
+    createdAt: number;
+}
+/** Input for listing a directory inside a grant. */
+export interface ILocalFolderListInput {
+    grantId: string;
+    /** Relative path. Empty lists the grant root. */
+    relPath?: string;
+    recursive?: boolean;
+}
+/** One directory entry. */
+export interface ILocalFolderEntry {
+    relPath: string;
+    name: string;
+    kind: LocalFolderEntryKind;
+    size: number;
+    mtimeMs: number;
+    inode: string;
+}
+/** Input for `stat`. */
+export interface ILocalFolderStatInput {
+    grantId: string;
+    relPath: string;
+}
+/** Input for a bounded read. `length` is capped at {@link LOCAL_FOLDERS_READ_RANGE_MAX}. */
+export interface ILocalFolderReadRangeInput {
+    grantId: string;
+    relPath: string;
+    offset: number;
+    length: number;
+}
+/** Bytes returned by `readRange`. `data` is a base64 string so it survives JSON tool results. */
+export interface ILocalFolderReadRangeResult {
+    dataBase64: string;
+    bytesRead: number;
+}
+/** Input for starting an index job. */
+export interface ILocalFolderIndexInput {
+    grantId: string;
+    /** Relative directory or file. Empty indexes the whole grant. */
+    relPath?: string;
+}
+/** Handle returned by `index`. */
+export interface ILocalFolderJobHandle {
+    jobId: string;
+}
+/** Input for `getFileBlocks`. */
+export interface ILocalFolderFileBlocksInput {
+    grantId: string;
+    /** Relative file path. */
+    relPath: string;
+}
+/** Indexed blocks for one file. `indexed` is false when the path has no index row. */
+export interface ILocalFolderFileBlocks {
+    indexed: boolean;
+    size?: number;
+    mtimeMs?: number;
+    blocks: {
+        hash: string;
+        size: number;
+    }[];
+}
+/** Index job snapshot returned by `getJob`. */
+export interface ILocalFolderJobInfo {
+    jobId: string;
+    kind: "index";
+    status: "running" | "done" | "error" | "cancelled";
+    done: number;
+    total: number;
+    error?: string;
+    result?: {
+        files: number;
+        rehashed: number;
+        skipped: number;
+        removed: number;
+    };
+}
+/** Input for `move`. */
+export interface ILocalFolderMoveInput {
+    grantId: string;
+    from: string;
+    to: string;
+}
+/** Input for `trash` and single-path tools. */
+export interface ILocalFolderPathInput {
+    grantId: string;
+    relPath: string;
+}
+/** Input for `purgeTrash`. */
+export interface ILocalFolderPurgeTrashInput {
+    grantId: string;
+    olderThanDays: number;
+}
+/** One path change inside a grant. */
+export interface ILocalFolderChange {
+    relPath: string;
+    kind: LocalFolderChangeKind;
+}
+/** Payload of the `changed` event. */
+export interface ILocalFolderChangedEvent {
+    grantId: string;
+    changes: ILocalFolderChange[];
+}
+/** Payload of the `jobProgress` event. */
+export interface ILocalFolderJobProgressEvent {
+    jobId: string;
+    done: number;
+    total: number;
+}
+/** Payload of the `jobFinished` event. */
+export interface ILocalFolderJobFinishedEvent {
+    jobId: string;
+    status: "done" | "error" | "cancelled";
+    error?: string;
+}
+/**
+ * Return the local-only System Local Folders contract shape.
+ *
+ * The host checks every path against an operator grant. Remote devices cannot call
+ * this contract; bytes between devices move through block exchange, not these tools.
+ */
+export declare function getLocalFoldersContractDefinition(): IContractDefinition;

package/dist/contracts/system/local-folders-contract.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localFoldersProviderPackageId = exports.LOCAL_FOLDERS_JOB_TTL_MS = exports.LOCAL_FOLDERS_RESERVED_DIR = exports.LOCAL_FOLDERS_CHUNK_MAX = exports.LOCAL_FOLDERS_CHUNK_AVG = exports.LOCAL_FOLDERS_CHUNK_MIN = exports.LOCAL_FOLDERS_READ_RANGE_MAX = exports.LOCAL_FOLDERS_CONTRACT_VERSION = void 0;
+exports.getLocalFoldersContractDefinition = getLocalFoldersContractDefinition;
+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 built-in System Local Folders contract. */
+exports.LOCAL_FOLDERS_CONTRACT_VERSION = 1;
+/** Maximum byte length accepted by `readRange` in one call. */
+exports.LOCAL_FOLDERS_READ_RANGE_MAX = 256 * 1024;
+/** FastCDC minimum block size. Files at or below this size are one block. */
+exports.LOCAL_FOLDERS_CHUNK_MIN = 256 * 1024;
+/** FastCDC target average block size. */
+exports.LOCAL_FOLDERS_CHUNK_AVG = 1024 * 1024;
+/** FastCDC maximum block size. */
+exports.LOCAL_FOLDERS_CHUNK_MAX = 4 * 1024 * 1024;
+/** Directory name reserved inside every grant for trash and in-flight files. */
+exports.LOCAL_FOLDERS_RESERVED_DIR = ".peers";
+/** How long finished index jobs stay readable via `getJob`. */
+exports.LOCAL_FOLDERS_JOB_TTL_MS = 60 * 60 * 1000;
+/** Package ID used by live System Local Folders tool instances. */
+exports.localFoldersProviderPackageId = system_ids_1.peersSystemPackageId;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+const grantIdField = field("grantId", field_type_1.FieldType.id, "Folder grant id.");
+let definition;
+/**
+ * Return the local-only System Local Folders contract shape.
+ *
+ * The host checks every path against an operator grant. Remote devices cannot call
+ * this contract; bytes between devices move through block exchange, not these tools.
+ */
+function getLocalFoldersContractDefinition() {
+    definition ??= {
+        contractId: system_ids_1.localFoldersContractId,
+        version: exports.LOCAL_FOLDERS_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Local Folders",
+        description: "Scoped access to operator-granted folders on this device: listing, bounded reads, indexing, move, and trash.",
+        tables: [],
+        tools: [
+            {
+                name: "requestGrant",
+                usageDescription: "Grant a local folder. Omit absolutePath on desktop to open the folder picker. Isolated packages cannot create grants.",
+                inputFields: [
+                    field("groupId", field_type_1.FieldType.id, "Group this folder is associated with."),
+                    field("mode", field_type_1.FieldType.string, 'Either "read" or "readwrite".'),
+                    field("packageId", field_type_1.FieldType.id, "Package allowed to use the grant.", {
+                        optional: true,
+                    }),
+                    field("absolutePath", field_type_1.FieldType.string, "Absolute directory path. Operator callers only. Omit to open the picker.", { optional: true }),
+                ],
+                outputFields: [
+                    grantIdField,
+                    field("groupId", field_type_1.FieldType.id, "Group id stored on the grant."),
+                    field("absolutePath", field_type_1.FieldType.string, "Absolute path of the granted root."),
+                    field("mode", field_type_1.FieldType.string, "Grant mode."),
+                    field("packageId", field_type_1.FieldType.id, "Package the grant is scoped to.", { optional: true }),
+                    field("createdAt", field_type_1.FieldType.number, "Creation time in unix epoch milliseconds."),
+                ],
+            },
+            {
+                name: "listGrants",
+                usageDescription: "List active grants. Isolated callers see only grants scoped to their package.",
+                inputFields: [],
+                outputFields: [
+                    field("grants", field_type_1.FieldType.object, "Active grants on this device.", { isArray: true }),
+                ],
+            },
+            {
+                name: "revokeGrant",
+                usageDescription: "Revoke a grant. Access stops immediately. Isolated callers can revoke only their own grants.",
+                inputFields: [grantIdField],
+                outputFields: [field("revoked", field_type_1.FieldType.boolean, "Whether the grant is now revoked.")],
+            },
+            {
+                name: "list",
+                usageDescription: "List entries under a relative path inside a grant. Skips .peers.",
+                inputFields: [
+                    grantIdField,
+                    field("relPath", field_type_1.FieldType.string, "Relative directory. Empty lists the root.", {
+                        optional: true,
+                    }),
+                    field("recursive", field_type_1.FieldType.boolean, "List the subtree.", { optional: true }),
+                ],
+                outputFields: [field("entries", field_type_1.FieldType.object, "Directory entries.", { isArray: true })],
+            },
+            {
+                name: "stat",
+                usageDescription: "Stat one relative path inside a grant.",
+                inputFields: [
+                    grantIdField,
+                    field("relPath", field_type_1.FieldType.string, "Relative path inside the grant."),
+                ],
+                outputFields: [
+                    field("relPath", field_type_1.FieldType.string, "Relative path."),
+                    field("name", field_type_1.FieldType.string, "Final path segment."),
+                    field("kind", field_type_1.FieldType.string, "file, dir, or symlink."),
+                    field("size", field_type_1.FieldType.number, "Size in bytes."),
+                    field("mtimeMs", field_type_1.FieldType.number, "mtime in unix epoch milliseconds."),
+                    field("inode", field_type_1.FieldType.string, "File identity string."),
+                ],
+            },
+            {
+                name: "readRange",
+                usageDescription: `Read up to ${exports.LOCAL_FOLDERS_READ_RANGE_MAX} bytes at an offset. Returns base64.`,
+                inputFields: [
+                    grantIdField,
+                    field("relPath", field_type_1.FieldType.string, "Relative file path."),
+                    field("offset", field_type_1.FieldType.number, "Byte offset."),
+                    field("length", field_type_1.FieldType.number, "Requested length, capped by the host."),
+                ],
+                outputFields: [
+                    field("dataBase64", field_type_1.FieldType.string, "File bytes encoded as base64."),
+                    field("bytesRead", field_type_1.FieldType.number, "Number of bytes read."),
+                ],
+            },
+            {
+                name: "index",
+                usageDescription: "Start a host job that content-defines and hashes files into the local block index. Requires a readwrite grant.",
+                inputFields: [
+                    grantIdField,
+                    field("relPath", field_type_1.FieldType.string, "Relative file or directory. Empty indexes the grant.", {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [field("jobId", field_type_1.FieldType.id, "Index job id.")],
+            },
+            {
+                name: "getFileBlocks",
+                usageDescription: "Return the indexed content-defined blocks for one file. Read mode is enough. indexed is false when the file has not been indexed.",
+                inputFields: [
+                    grantIdField,
+                    field("relPath", field_type_1.FieldType.string, "Relative file path inside the grant."),
+                ],
+                outputFields: [
+                    field("indexed", field_type_1.FieldType.boolean, "Whether an index row exists for this path."),
+                    field("size", field_type_1.FieldType.number, "File size in bytes at index time.", { optional: true }),
+                    field("mtimeMs", field_type_1.FieldType.number, "mtime in unix epoch milliseconds.", {
+                        optional: true,
+                    }),
+                    field("blocks", field_type_1.FieldType.object, "Ordered blocks with hash and size.", {
+                        isArray: true,
+                    }),
+                ],
+            },
+            {
+                name: "getJob",
+                usageDescription: "Return the status of an index job, including after it finishes.",
+                inputFields: [field("jobId", field_type_1.FieldType.id, "Job id returned by index.")],
+                outputFields: [
+                    field("jobId", field_type_1.FieldType.id, "Job id."),
+                    field("kind", field_type_1.FieldType.string, "Job kind. v1 is index."),
+                    field("status", field_type_1.FieldType.string, "running, done, error, or cancelled."),
+                    field("done", field_type_1.FieldType.number, "Units completed."),
+                    field("total", field_type_1.FieldType.number, "Units discovered."),
+                    field("error", field_type_1.FieldType.string, "Failure message.", { optional: true }),
+                    field("result", field_type_1.FieldType.object, "Index counts when status is done.", {
+                        optional: true,
+                    }),
+                ],
+            },
+            {
+                name: "cancelJob",
+                usageDescription: "Cancel a running index job.",
+                inputFields: [field("jobId", field_type_1.FieldType.id, "Job id returned by index.")],
+                outputFields: [field("cancelled", field_type_1.FieldType.boolean, "Whether the job was cancelled.")],
+            },
+            {
+                name: "move",
+                usageDescription: "Move a path inside a readwrite grant. Atomic where the OS allows.",
+                inputFields: [
+                    grantIdField,
+                    field("from", field_type_1.FieldType.string, "Relative source path."),
+                    field("to", field_type_1.FieldType.string, "Relative destination path."),
+                ],
+                outputFields: [field("moved", field_type_1.FieldType.boolean, "Whether the move completed.")],
+            },
+            {
+                name: "trash",
+                usageDescription: "Move a path to .peers/trash/<date>/ inside a readwrite grant.",
+                inputFields: [grantIdField, field("relPath", field_type_1.FieldType.string, "Relative path to trash.")],
+                outputFields: [
+                    field("trashed", field_type_1.FieldType.boolean, "Whether the path was moved to trash."),
+                    field("trashPath", field_type_1.FieldType.string, "Relative path inside the grant trash."),
+                ],
+            },
+            {
+                name: "purgeTrash",
+                usageDescription: "Delete trash entries older than the given number of days.",
+                inputFields: [
+                    grantIdField,
+                    field("olderThanDays", field_type_1.FieldType.number, "Delete trash dated strictly before this many days ago."),
+                ],
+                outputFields: [field("removed", field_type_1.FieldType.number, "Number of trash entries removed.")],
+            },
+        ],
+        observables: [],
+        events: [
+            {
+                name: "changed",
+                description: "Debounced filesystem changes inside a grant. The reserved .peers directory is omitted. v1 hosts emit created, modified, and deleted. renamed is reserved for a later host.",
+                payloadFields: [
+                    grantIdField,
+                    field("changes", field_type_1.FieldType.object, "Changes with relPath and kind. v1 hosts emit created, modified, or deleted. renamed is reserved.", { isArray: true }),
+                ],
+            },
+            {
+                name: "jobProgress",
+                description: "Progress for a host index job.",
+                payloadFields: [
+                    field("jobId", field_type_1.FieldType.id, "Job id."),
+                    field("done", field_type_1.FieldType.number, "Units completed."),
+                    field("total", field_type_1.FieldType.number, "Units discovered."),
+                ],
+            },
+            {
+                name: "jobFinished",
+                description: "An index job finished, failed, or was cancelled.",
+                payloadFields: [
+                    field("jobId", field_type_1.FieldType.id, "Job id."),
+                    field("status", field_type_1.FieldType.string, "done, error, or cancelled."),
+                    field("error", field_type_1.FieldType.string, "Failure message.", { optional: true }),
+                ],
+            },
+        ],
+    };
+    return definition;
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.localFoldersContractId,
+    version: exports.LOCAL_FOLDERS_CONTRACT_VERSION,
+    getDefinition: getLocalFoldersContractDefinition,
+});

package/dist/data/index.d.ts

@@ -14,6 +14,7 @@ export * from "./group-secret";
 export * from "./group-share";
 export * from "./groups";
 export * from "./invites";
+export * from "./local-folders";
 export * from "./messages";
 export * from "./package-table-identity";
 export * from "./package-version-resolver";

package/dist/data/index.js

@@ -30,6 +30,7 @@ __exportStar(require("./group-secret"), exports);
 __exportStar(require("./group-share"), exports);
 __exportStar(require("./groups"), exports);
 __exportStar(require("./invites"), exports);
+__exportStar(require("./local-folders"), exports);
 __exportStar(require("./messages"), exports);
 __exportStar(require("./package-table-identity"), exports);
 __exportStar(require("./package-version-resolver"), exports);

package/dist/data/local-folders.d.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+import { type ITableMetaData } from "./orm/types";
+/** Content-defined block descriptor stored on an indexed file. */
+export declare const localFolderBlockSchema: z.ZodObject<{
+    hash: z.ZodString;
+    size: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    size: number;
+    hash: string;
+}, {
+    size: number;
+    hash: string;
+}>;
+/** One content-defined block: hash and length. */
+export type ILocalFolderBlock = z.infer<typeof localFolderBlockSchema>;
+/** Access mode recorded on a folder grant. */
+export declare const localFolderGrantModeSchema: z.ZodEnum<["read", "readwrite"]>;
+/** `read` lists and reads; `readwrite` may also move, trash, and index. */
+export type LocalFolderGrantMode = z.infer<typeof localFolderGrantModeSchema>;
+/**
+ * Operator grant of one absolute folder to an optional package.
+ * Stored only on this device, in the personal database.
+ */
+export declare const localFolderGrantSchema: z.ZodObject<{
+    grantId: z.ZodEffects<z.ZodString, string, string>;
+    packageId: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    groupId: z.ZodEffects<z.ZodString, string, string>;
+    absolutePath: z.ZodString;
+    mode: z.ZodEnum<["read", "readwrite"]>;
+    createdAt: z.ZodNumber;
+    revokedAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    groupId: string;
+    createdAt: number;
+    mode: "readwrite" | "read";
+    grantId: string;
+    absolutePath: string;
+    packageId?: string | undefined;
+    revokedAt?: number | undefined;
+}, {
+    groupId: string;
+    createdAt: number;
+    mode: "readwrite" | "read";
+    grantId: string;
+    absolutePath: string;
+    packageId?: string | undefined;
+    revokedAt?: number | undefined;
+}>;
+/** A device-local folder grant. */
+export type ILocalFolderGrant = z.infer<typeof localFolderGrantSchema>;
+/** Indexed file under a grant. One row per `(grantId, relPath)`. */
+export declare const localFolderFileSchema: z.ZodObject<{
+    fileIndexId: z.ZodEffects<z.ZodString, string, string>;
+    grantId: z.ZodEffects<z.ZodString, string, string>;
+    relPath: z.ZodString;
+    size: z.ZodNumber;
+    mtimeMs: z.ZodNumber;
+    inode: z.ZodString;
+    blocks: z.ZodArray<z.ZodObject<{
+        hash: z.ZodString;
+        size: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        size: number;
+        hash: string;
+    }, {
+        size: number;
+        hash: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    size: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    inode: string;
+    blocks: {
+        size: number;
+        hash: string;
+    }[];
+    fileIndexId: string;
+}, {
+    size: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    inode: string;
+    blocks: {
+        size: number;
+        hash: string;
+    }[];
+    fileIndexId: string;
+}>;
+/** A local index row for one file. */
+export type ILocalFolderFile = z.infer<typeof localFolderFileSchema>;
+/**
+ * One servable block location. The same hash may appear in several files;
+ * `blockHash` is indexed, not unique.
+ */
+export declare const localFolderBlockRowSchema: z.ZodObject<{
+    blockRowId: z.ZodEffects<z.ZodString, string, string>;
+    blockHash: z.ZodString;
+    grantId: z.ZodEffects<z.ZodString, string, string>;
+    relPath: z.ZodString;
+    offset: z.ZodNumber;
+    length: z.ZodNumber;
+    mtimeMs: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    length: number;
+    offset: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    blockRowId: string;
+    blockHash: string;
+}, {
+    length: number;
+    offset: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    blockRowId: string;
+    blockHash: string;
+}>;
+/** A local index row mapping a block hash to a byte range in a real file. */
+export type ILocalFolderBlockRow = z.infer<typeof localFolderBlockRowSchema>;
+/** Table metadata for {@link LocalFolderGrants}. */
+export declare const localFolderGrantsMetaData: ITableMetaData;
+/** Table metadata for {@link LocalFolderFiles}. */
+export declare const localFolderFilesMetaData: ITableMetaData;
+/** Table metadata for {@link LocalFolderBlocks}. */
+export declare const localFolderBlocksMetaData: ITableMetaData;
+/**
+ * Device-local folder grants. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the grants. Defaults to the current context.
+ */
+export declare function LocalFolderGrants(dataContext?: DataContext): import("..").Table<{
+    groupId: string;
+    createdAt: number;
+    mode: "readwrite" | "read";
+    grantId: string;
+    absolutePath: string;
+    packageId?: string | undefined;
+    revokedAt?: number | undefined;
+}>;
+/**
+ * Device-local indexed files. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+export declare function LocalFolderFiles(dataContext?: DataContext): import("..").Table<{
+    size: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    inode: string;
+    blocks: {
+        size: number;
+        hash: string;
+    }[];
+    fileIndexId: string;
+}>;
+/**
+ * Device-local block locations. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+export declare function LocalFolderBlocks(dataContext?: DataContext): import("..").Table<{
+    length: number;
+    offset: number;
+    grantId: string;
+    relPath: string;
+    mtimeMs: number;
+    blockRowId: string;
+    blockHash: string;
+}>;

package/dist/data/local-folders.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localFolderBlocksMetaData = exports.localFolderFilesMetaData = exports.localFolderGrantsMetaData = exports.localFolderBlockRowSchema = exports.localFolderFileSchema = exports.localFolderGrantSchema = exports.localFolderGrantModeSchema = exports.localFolderBlockSchema = void 0;
+exports.LocalFolderGrants = LocalFolderGrants;
+exports.LocalFolderFiles = LocalFolderFiles;
+exports.LocalFolderBlocks = LocalFolderBlocks;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const zod_types_1 = require("../types/zod-types");
+const table_definitions_system_1 = require("./orm/table-definitions.system");
+const types_1 = require("./orm/types");
+/** Content-defined block descriptor stored on an indexed file. */
+exports.localFolderBlockSchema = zod_1.z.object({
+    hash: zod_1.z.string().describe("SHA-256 hex digest of the block bytes."),
+    size: zod_1.z.number().describe("Block length in bytes."),
+});
+/** Access mode recorded on a folder grant. */
+exports.localFolderGrantModeSchema = zod_1.z.enum(["read", "readwrite"]);
+/**
+ * Operator grant of one absolute folder to an optional package.
+ * Stored only on this device, in the personal database.
+ */
+exports.localFolderGrantSchema = zod_1.z.object({
+    grantId: zod_types_1.zodPeerId.describe("Grant id."),
+    packageId: zod_types_1.zodPeerId
+        .optional()
+        .describe("Isolated package allowed to use this grant. Absent for operator-owned grants."),
+    groupId: zod_types_1.zodPeerId.describe("Group the folder is associated with."),
+    absolutePath: zod_1.z.string().describe("Absolute filesystem path of the granted root."),
+    mode: exports.localFolderGrantModeSchema.describe("Whether the grant allows writes."),
+    createdAt: zod_1.z.number().describe("Unix epoch milliseconds when the grant was created."),
+    revokedAt: zod_1.z
+        .number()
+        .optional()
+        .describe("Unix epoch milliseconds when the grant was revoked. Absent while active."),
+});
+/** Indexed file under a grant. One row per `(grantId, relPath)`. */
+exports.localFolderFileSchema = zod_1.z.object({
+    fileIndexId: zod_types_1.zodPeerId.describe("Index row id."),
+    grantId: zod_types_1.zodPeerId.describe("Grant this file belongs to."),
+    relPath: zod_1.z.string().describe("Path relative to the grant root, `/`-separated, NFC."),
+    size: zod_1.z.number().describe("File size in bytes at index time."),
+    mtimeMs: zod_1.z.number().describe("File mtime in milliseconds at index time."),
+    inode: zod_1.z.string().describe("File identity string (`stat.ino`) at index time."),
+    blocks: zod_1.z.array(exports.localFolderBlockSchema).describe("Ordered content-defined blocks."),
+});
+/**
+ * One servable block location. The same hash may appear in several files;
+ * `blockHash` is indexed, not unique.
+ */
+exports.localFolderBlockRowSchema = zod_1.z.object({
+    blockRowId: zod_types_1.zodPeerId.describe("Block-location row id."),
+    blockHash: zod_1.z.string().describe("SHA-256 hex digest of the block bytes."),
+    grantId: zod_types_1.zodPeerId.describe("Grant whose file contains the block."),
+    relPath: zod_1.z.string().describe("File path relative to the grant root."),
+    offset: zod_1.z.number().describe("Byte offset of the block within the file."),
+    length: zod_1.z.number().describe("Block length in bytes."),
+    mtimeMs: zod_1.z.number().describe("File mtime in milliseconds when the block was indexed."),
+});
+const grantMetaData = {
+    name: "LocalFolderGrants",
+    description: "Device-local scoped folder grants for System Local Folders.",
+    primaryKeyName: "grantId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderGrantSchema),
+    localOnly: true,
+    indexes: [{ fields: ["packageId"] }, { fields: ["groupId"] }],
+};
+const fileMetaData = {
+    name: "LocalFolderFiles",
+    description: "Device-local file index for System Local Folders.",
+    primaryKeyName: "fileIndexId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderFileSchema),
+    localOnly: true,
+    indexes: [{ fields: ["grantId", "relPath"], unique: true }, { fields: ["grantId"] }],
+};
+const blockMetaData = {
+    name: "LocalFolderBlocks",
+    description: "Device-local block locations for System Local Folders.",
+    primaryKeyName: "blockRowId",
+    fields: (0, types_1.schemaToFields)(exports.localFolderBlockRowSchema),
+    localOnly: true,
+    indexes: [{ fields: ["blockHash"] }, { fields: ["grantId", "relPath"] }],
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(grantMetaData, exports.localFolderGrantSchema);
+(0, table_definitions_system_1.registerSystemTableDefinition)(fileMetaData, exports.localFolderFileSchema);
+(0, table_definitions_system_1.registerSystemTableDefinition)(blockMetaData, exports.localFolderBlockRowSchema);
+/** Table metadata for {@link LocalFolderGrants}. */
+exports.localFolderGrantsMetaData = grantMetaData;
+/** Table metadata for {@link LocalFolderFiles}. */
+exports.localFolderFilesMetaData = fileMetaData;
+/** Table metadata for {@link LocalFolderBlocks}. */
+exports.localFolderBlocksMetaData = blockMetaData;
+/**
+ * Device-local folder grants. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the grants. Defaults to the current context.
+ */
+function LocalFolderGrants(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(grantMetaData, exports.localFolderGrantSchema);
+}
+/**
+ * Device-local indexed files. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+function LocalFolderFiles(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(fileMetaData, exports.localFolderFileSchema);
+}
+/**
+ * Device-local block locations. Pass the personal data context; these rows do not sync.
+ *
+ * @param dataContext Context whose database holds the index. Defaults to the current context.
+ */
+function LocalFolderBlocks(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(blockMetaData, exports.localFolderBlockRowSchema);
+}

package/dist/system-ids.d.ts

@@ -93,3 +93,25 @@ export declare const identityToolIds: {
     readonly signOut: "00muc9mlzxwdm2yj5p5wkjvz7";
     readonly registerWithPeersServices: "00muc9mlzx07q98l3f9x49o10";
 };
+/**
+ * Contract id for the local-only System Local Folders surface (`system.fs`).
+ * Scoped folder grants, directory listing, and host-side indexing. Not available
+ * over device-to-device connections; block exchange is a separate path.
+ */
+export declare const localFoldersContractId = "00mukk9dwb1mjtd845kftuazm";
+/** Stable IDs for tools in System Local Folders v1. */
+export declare const localFoldersToolIds: {
+    readonly requestGrant: "00mukk9dwdcv4f99ydwxao97f";
+    readonly listGrants: "00mukk9dwdq119xmvz4ap8aum";
+    readonly revokeGrant: "00mukk9dwdezt5sbjviq1n1sp";
+    readonly list: "00mukk9dwd6mxscrv9eeaanai";
+    readonly stat: "00mukk9dwdon2y2487clcg67k";
+    readonly readRange: "00mukk9dwdih6mh8rrofph80o";
+    readonly index: "00mukk9dwdm01bxg3hrby6pli";
+    readonly getFileBlocks: "00mumw1pmmf3y2ujfdc99h4ib";
+    readonly getJob: "00mukk9dwd1c1f51xjysssgtv";
+    readonly cancelJob: "00mukk9dweizvif4ghp6kfa92";
+    readonly move: "00mukk9dwer8wsw5eiwis8tzm";
+    readonly trash: "00mukk9dwejbuehqzszpyxefx";
+    readonly purgeTrash: "00mukk9dwe6co8gvuy44kmuzd";
+};

package/dist/system-ids.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
 /** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
 /** Default assistant used when no user-selected assistant is available. */
@@ -97,3 +97,25 @@ exports.identityToolIds = {
     signOut: "00muc9mlzxwdm2yj5p5wkjvz7",
     registerWithPeersServices: "00muc9mlzx07q98l3f9x49o10",
 };
+/**
+ * Contract id for the local-only System Local Folders surface (`system.fs`).
+ * Scoped folder grants, directory listing, and host-side indexing. Not available
+ * over device-to-device connections; block exchange is a separate path.
+ */
+exports.localFoldersContractId = "00mukk9dwb1mjtd845kftuazm";
+/** Stable IDs for tools in System Local Folders v1. */
+exports.localFoldersToolIds = {
+    requestGrant: "00mukk9dwdcv4f99ydwxao97f",
+    listGrants: "00mukk9dwdq119xmvz4ap8aum",
+    revokeGrant: "00mukk9dwdezt5sbjviq1n1sp",
+    list: "00mukk9dwd6mxscrv9eeaanai",
+    stat: "00mukk9dwdon2y2487clcg67k",
+    readRange: "00mukk9dwdih6mh8rrofph80o",
+    index: "00mukk9dwdm01bxg3hrby6pli",
+    getFileBlocks: "00mumw1pmmf3y2ujfdc99h4ib",
+    getJob: "00mukk9dwd1c1f51xjysssgtv",
+    cancelJob: "00mukk9dweizvif4ghp6kfa92",
+    move: "00mukk9dwer8wsw5eiwis8tzm",
+    trash: "00mukk9dwejbuehqzszpyxefx",
+    purgeTrash: "00mukk9dwe6co8gvuy44kmuzd",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.25.9",
+  "version": "0.25.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"