@hachej/boring-files 0.2.0 → 0.2.2

package/README.md

@@ -10,6 +10,12 @@ Opaque resource view IDs are provider-scoped and bound to the actual backing/inc
 
 The provider accepts all-or-nothing create and replace. It refuses working views, per-change requests and deletes (files are removed with the workspace's own tools) before any effect. Logical paths are relative to the workspace root; a path whose real location leaves the root is denied. A single file is replaced atomically by every backend; a multi-file batch only by the SQLite backend, together with its receipt when the journal shares the database. Access control is the host's, at the workspace boundary: there are no per-file permissions inside a workspace, and external revocation fencing is not implemented.
 
+### Agent writes and the change feed
+
+Agent writes are observed, never receipted ([owner ruling 2](../../docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)). `provider.record({ path, before?, after, source: 'agent', conversationId? }, access)` is what the file guard (`@hachej/boring-agent/file-guard`) calls after a Pi `write` or `edit` succeeded: the file's history gains the written revision with `source: 'agent'` (and the replaced revision, `source: 'observed'`, when `before` carries its bytes), and the change feed an `agent` event. It never writes the publication journal and never mints a receipt. It does not enter the provider's queue (the guard already runs inside it), so calling it from queued work cannot deadlock. History entries (`saves`, `catalog.history`) carry `source`: `publish`, `agent` or `observed` (`keep` and replaced revisions).
+
+`provider.changes({ since?, signal }, access)` is one change feed for every file view: an `AsyncIterable` of `{ kind: 'change', path, revision | null, source: 'publish' | 'agent' | 'poll' | 'watch', seq, at }`, ordered by `seq` and replayable from `since` (the last `seq` seen; `changeHead()` is "now"). The provider retains the last `changeBuffer` events (default 1024); a cursor older than that, from another provider lifetime or ahead of this one, and a listener that falls behind get `{ kind: 'resnapshot', seq, at }`: reload everything shown, then continue. Events are invalidation hints; bytes and the journal stay authoritative. Sources: conditional writes (`publish`), `record` (`agent`), `poll` and, while someone listens (and `watchLingerMs` after, default 30 s), the file system's own `watch` (`watch`; a reported directory is `{ revision: null, directory: true }`). The SQLite file system reports writes through its own connection at once and polls every second for other connections. When the file system cannot watch (the virtual and remote environments report `not_supported`), the host calls `provider.poll()` at the end of each agent turn: without paths it hashes every file (not `.git` or `node_modules`); the first call takes the baseline, later ones report changed, new and removed files. A `bash` write gets change events only, never history. After the last listener leaves the watcher lingers and then closes; changes made while no watcher was open are unknown, so the first listener afterwards makes the feed append a `resnapshot` (a client that stays connected is never affected). `changeIncarnation` names the provider lifetime: a cursor sent with another `incarnation` is a `resnapshot` whatever its number. `provider.close()` ends every change stream, closes the watcher and drops the listeners.
+
 Receipts are scoped by workspace identity, principal, scope and initiator. Identical committed retries return the original receipt; changed arguments conflict. Refused operations do not reserve an ID. A receipt from an earlier incarnation of the workspace reads `unknown`. A not-found lookup is not permission to replay an uncertain operation.
 
 `@hachej/boring-files/publication` is browser-safe. It captures request bytes, computes a versioned canonical SHA-256 digest with WebCrypto, and parses result shapes. Digests carry `boring-publication-v1:sha256:` and bind that format identifier in the hashed payload. Consumers must also check operation, target, scope and index association against their own request. This module confers no authorization. The SQLite connection (`openNodeConnection` from `@hachej/boring-files/sqlite`) is a separate server entry point.
@@ -138,7 +144,21 @@ const revisionProvider = await connectRevisionProvider({
 
 The binding discovers identity and workspace incarnation from the authenticated
 server. Reconnect when the selected workspace changes. It exposes `list`,
-filename `search`, retained `history`, `locate`, `read`, `publish` and `lookup`.
+filename `search`, retained `history`, `locate`, `read`, `publish`, `lookup` and
+`changes({ since?, signal })`, the workspace's change feed.
+
+The feed is `GET <endpoint>?op=changes[&since=<seq>&incarnation=<id>]` with the binding header:
+server-sent events (`event: ready` with the current seq and the provider incarnation, then `event: change` or
+`event: resnapshot` with `id:` the seq and the JSON event as `data:`), and a
+comment line every `heartbeatMs` (`createRevisionHandler({ resolve, heartbeatMs })`,
+default 15 s). It is a plain streamed response with no queue (pull-based), so a slow client
+costs the provider's bounded replay buffer and a `resnapshot`, never memory in
+the handler; revocation discards anything unread. It runs on Node and Workers
+alike. The handler holds the workspace lease for the life of the stream and
+releases it when the client disconnects or its access signal aborts; a request
+the host refuses, or whose binding names another workspace or identity, gets no
+event (403 or 409). The client reconnects after the last seq it delivered, with
+backoff, until its `signal` aborts; a refusal ends it with a `RevisionError`.
 All writes use conditional publication; uploading a new file requires absence,
 and replacing one requires its exact resource revision. An unknown result must
 be reconciled by operation ID before another upload to that path.

package/dist/contracts.d.ts

@@ -132,6 +132,14 @@ export type PublicationRefusal = {
 } | {
     readonly kind: 'unavailable';
     readonly reason: string;
+}
+/** A change above the provider's byte limit: permanent for these bytes, nothing was written. */
+ | {
+    readonly kind: 'file_too_large';
+    readonly path: string;
+    readonly size: number;
+    readonly limit: number;
+    readonly reason: string;
 };
 export type PublicationOutcome = {
     readonly kind: 'committed';

package/dist/file-limits.d.ts

@@ -0,0 +1,10 @@
+import { FileError } from '@earendil-works/pi-durable/env';
+export declare const SQLITE_MAX_FILE_BYTES = 1900000;
+/** A limit is a non-negative safe integer of bytes. */
+export declare function assertLimit(value: unknown): asserts value is number;
+/**
+ * A write above the limit. Pi's `FileErrorCode` has no size code and Pi is not patched, so this is an `invalid` error whose message
+ * starts with the POSIX `EFBIG` name, like the other errors of the file system.
+ */
+export declare function fileTooLarge(path: string, size: number, limit: number): FileError;
+//# sourceMappingURL=file-limits.d.ts.map

package/dist/file-limits.js

@@ -0,0 +1,16 @@
+// The largest file a SQLite-backed workspace stores by default: a Durable Object's SQL storage caps one row (and so one file's bytes)
+// at 2 MB, so the default leaves headroom for the row's other columns. Disk and remote providers have no default limit.
+import { FileError } from '@earendil-works/pi-durable/env';
+export const SQLITE_MAX_FILE_BYTES = 1_900_000;
+/** A limit is a non-negative safe integer of bytes. */
+export function assertLimit(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new TypeError('maxFileBytes must be a non-negative safe integer');
+}
+/**
+ * A write above the limit. Pi's `FileErrorCode` has no size code and Pi is not patched, so this is an `invalid` error whose message
+ * starts with the POSIX `EFBIG` name, like the other errors of the file system.
+ */
+export function fileTooLarge(path, size, limit) {
+    return new FileError('invalid', `EFBIG: file_too_large: ${size} bytes exceeds the ${limit} byte limit, '${path}'`, path);
+}

package/dist/file-types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The one place boring-files says what a file is: its extension, its media type (by name and by leading bytes), the viewer that
+ * opens it, the provider's temporary and hidden names, the workspace path a user or agent typed, and the name of a new upload.
+ * Callers import these; none keeps a copy. Pure: no Node, no DOM.
+ */
+/** The lower-case extension of the last path segment, or ''. */
+export declare const extensionOf: (path: string) => string;
+/** The IANA media type by extension. Anything not listed is `application/octet-stream` (see `mediaTypeOf`). Null-prototype: `constructor` or `__proto__` is not an entry. */
+export declare const MEDIA_TYPES: Readonly<Record<string, string>>;
+/** The IANA media type of a path, `application/octet-stream` when unknown. */
+export declare const mediaTypeOf: (path: string) => string;
+/** The media type a file's leading bytes name (a PDF, PNG, JPEG, GIF or WebP signature), or undefined. */
+export declare function sniffMediaType(head: Uint8Array): string | undefined;
+/** Which viewer opens a file. Anything not listed is shown as text when it decodes. */
+export type ViewerKind = 'markdown' | 'html' | 'canvas' | 'image' | 'pdf' | 'text';
+/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf` or `text`. */
+export declare const viewerKindOf: (path: string) => ViewerKind;
+/** Binary viewers never decode a file as text, whatever its bytes look like (an SVG is text). */
+export declare const isBinaryKind: (path: string) => boolean;
+/** The basename of a new temporary file, for a provider's `uuid`. */
+export declare const temporaryFileName: (uuid: string) => string;
+/** Whether a path's last segment is one of the provider's temporary files (a lister hides them). */
+export declare const isTemporary: (path: string) => boolean;
+/** Names a presentation listing hides by default (dependency, build and internal folders, and the provider's own). Not an access policy. */
+export declare const HIDDEN_NAMES: ReadonlySet<string>;
+/** A path as a person or agent typed it, as a workspace-relative resource path: leading `./` segments removed. A leading `/` stays: it is not a workspace path, and the provider refuses it rather than reading it as a relative one. */
+export declare const workspacePath: (path: string) => string;
+/** A new upload's workspace path: `uploads/<stem>-<8 hex>.<ext>`, so a second `image.png` (every pasted screenshot has that name) is a new file beside the first. Whitespace becomes `_`, because a chat mention ends at a space. */
+export declare function uploadPath(name: string, randomSuffix: string): string;
+//# sourceMappingURL=file-types.d.ts.map

package/dist/file-types.js

@@ -0,0 +1,61 @@
+/**
+ * The one place boring-files says what a file is: its extension, its media type (by name and by leading bytes), the viewer that
+ * opens it, the provider's temporary and hidden names, the workspace path a user or agent typed, and the name of a new upload.
+ * Callers import these; none keeps a copy. Pure: no Node, no DOM.
+ */
+/** The lower-case extension of the last path segment, or ''. */
+export const extensionOf = (path) => { const dot = path.lastIndexOf('.'); return dot > path.lastIndexOf('/') ? path.slice(dot + 1).toLowerCase() : ''; };
+/** The IANA media type by extension. Anything not listed is `application/octet-stream` (see `mediaTypeOf`). Null-prototype: `constructor` or `__proto__` is not an entry. */
+export const MEDIA_TYPES = Object.assign(Object.create(null), {
+    md: 'text/markdown', markdown: 'text/markdown', html: 'text/html', htm: 'text/html', json: 'application/json', svg: 'image/svg+xml',
+    txt: 'text/plain', csv: 'text/csv', js: 'text/javascript', mjs: 'text/javascript', css: 'text/css', tldraw: 'application/vnd.tldraw+json',
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', bmp: 'image/bmp', tif: 'image/tiff', tiff: 'image/tiff',
+    pdf: 'application/pdf', doc: 'application/msword', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    odt: 'application/vnd.oasis.opendocument.text', ods: 'application/vnd.oasis.opendocument.spreadsheet', odp: 'application/vnd.oasis.opendocument.presentation',
+    rtf: 'application/rtf', epub: 'application/epub+zip',
+});
+/** The IANA media type of a path, `application/octet-stream` when unknown. */
+export const mediaTypeOf = (path) => MEDIA_TYPES[extensionOf(path)] ?? 'application/octet-stream';
+/** The media type a file's leading bytes name (a PDF, PNG, JPEG, GIF or WebP signature), or undefined. */
+export function sniffMediaType(head) {
+    const at = (signature, offset = 0) => signature.every((byte, index) => head[offset + index] === byte);
+    if (at([0x25, 0x50, 0x44, 0x46, 0x2d]))
+        return 'application/pdf';
+    if (at([0x89, 0x50, 0x4e, 0x47]))
+        return 'image/png';
+    if (at([0xff, 0xd8, 0xff]))
+        return 'image/jpeg';
+    if (at([0x47, 0x49, 0x46, 0x38]))
+        return 'image/gif';
+    if (at([0x52, 0x49, 0x46, 0x46]) && at([0x57, 0x45, 0x42, 0x50], 8))
+        return 'image/webp';
+    return undefined;
+}
+const VIEWER_KINDS = Object.assign(Object.create(null), {
+    md: 'markdown', markdown: 'markdown', html: 'html', htm: 'html', tldraw: 'canvas',
+    png: 'image', jpg: 'image', jpeg: 'image', gif: 'image', webp: 'image', svg: 'image', pdf: 'pdf',
+    txt: 'text', json: 'text', csv: 'text', js: 'text', mjs: 'text', css: 'text',
+});
+/** The viewer kind of a path: `markdown`, `html`, `canvas`, `image`, `pdf` or `text`. */
+export const viewerKindOf = (path) => VIEWER_KINDS[extensionOf(path)] ?? 'text';
+/** Binary viewers never decode a file as text, whatever its bytes look like (an SVG is text). */
+export const isBinaryKind = (path) => ['image', 'pdf'].includes(viewerKindOf(path)) && extensionOf(path) !== 'svg';
+/** The provider's temporary files are named `.boring-<uuid>.tmp` beside their target. They are removed when the provider opens and are never a resource. */
+const temporaryPattern = /^\.boring-[0-9a-f-]{36}\.tmp$/;
+/** The basename of a new temporary file, for a provider's `uuid`. */
+export const temporaryFileName = (uuid) => `.boring-${uuid}.tmp`;
+/** Whether a path's last segment is one of the provider's temporary files (a lister hides them). */
+export const isTemporary = (path) => temporaryPattern.test(path.slice(path.lastIndexOf('/') + 1));
+/** Names a presentation listing hides by default (dependency, build and internal folders, and the provider's own). Not an access policy. */
+export const HIDDEN_NAMES = new Set(['.git', '.boring', 'node_modules', 'dist', 'build', '.cache', '.next', 'coverage', '__pycache__']);
+/** A path as a person or agent typed it, as a workspace-relative resource path: leading `./` segments removed. A leading `/` stays: it is not a workspace path, and the provider refuses it rather than reading it as a relative one. */
+export const workspacePath = (path) => path.replace(/^(\.\/)+/, '');
+/** A new upload's workspace path: `uploads/<stem>-<8 hex>.<ext>`, so a second `image.png` (every pasted screenshot has that name) is a new file beside the first. Whitespace becomes `_`, because a chat mention ends at a space. */
+export function uploadPath(name, randomSuffix) {
+    const dot = name.lastIndexOf('.');
+    const [stem, extension] = dot > 0 ? [name.slice(0, dot), name.slice(dot)] : [name, ''];
+    const safe = (part) => part.replace(/\s+/g, '_');
+    return `uploads/${safe(stem)}-${randomSuffix}${safe(extension)}`;
+}

package/dist/journal.d.ts

@@ -38,7 +38,13 @@ export interface StoredVersion {
     readonly mediaType: string;
     /** When this revision was saved, in milliseconds since the epoch. Kept the first time the revision is retained. */
     readonly savedAt?: number;
+    /**
+     * Who produced the revision: `publish` (a conditional write), `agent` (a Pi `write` or `edit`, recorded by `provider.record`: it
+     * has no receipt) or `observed` (retained as found: `keep`, or the replaced revision of a write). Default `publish`.
+     */
+    readonly source?: HistorySource;
 }
+export type HistorySource = 'publish' | 'agent' | 'observed';
 /**
  * The operation journal plus what a workspace needs beyond receipts: an intent row written before an operation's first effect
  * (an intent without a completion is an operation of unknown outcome), and the last versions of each file when there is no Git.
@@ -68,6 +74,7 @@ export interface WorkspaceJournal extends OperationJournal {
     readonly saves: (scope: string, path: string) => {
         readonly revision: string;
         readonly savedAt: number;
+        readonly source: HistorySource;
     }[];
 }
 export declare function createWorkspaceJournal(db: SqliteConnection, options?: {

package/dist/journal.js

@@ -59,6 +59,7 @@ export function committedChanges(changes, ref) {
         throw new Error('Stored operation has no changes');
     return [first, ...rest];
 }
+const historySource = (value) => value === 'agent' || value === 'observed' ? value : 'publish';
 export function createWorkspaceJournal(db, options = {}) {
     const limit = options.historyLimit ?? 20;
     if (!Number.isSafeInteger(limit) || limit < 1)
@@ -74,18 +75,22 @@ export function createWorkspaceJournal(db, options = {}) {
       ) STRICT;
       CREATE TABLE IF NOT EXISTS boring_history (
         scope TEXT NOT NULL, path TEXT NOT NULL, revision TEXT NOT NULL, sequence INTEGER NOT NULL,
-        bytes BLOB NOT NULL, media_type TEXT NOT NULL, saved_at INTEGER NOT NULL DEFAULT 0,
+        bytes BLOB NOT NULL, media_type TEXT NOT NULL, saved_at INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'publish',
         PRIMARY KEY (scope, path, revision)
       ) STRICT;
     `);
         // A journal created before save times were recorded gets the column; its old rows read as unknown (0).
         if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'saved_at'))
             db.exec('ALTER TABLE boring_history ADD COLUMN saved_at INTEGER NOT NULL DEFAULT 0');
+        // A journal created before history recorded who wrote each revision: its old rows were all conditional writes.
+        if (!db.all("SELECT name FROM pragma_table_info('boring_history')").some(column => column.name === 'source'))
+            db.exec("ALTER TABLE boring_history ADD COLUMN source TEXT NOT NULL DEFAULT 'publish'");
     });
     const remember = (scope, path, version) => {
         const last = db.get('SELECT COALESCE(MAX(sequence), 0) AS last FROM boring_history WHERE scope = ? AND path = ?', scope, path);
         const sequence = Number(last?.last ?? 0) + 1;
-        db.run('INSERT INTO boring_history (scope, path, revision, sequence, bytes, media_type, saved_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(scope, path, revision) DO UPDATE SET sequence = excluded.sequence, bytes = excluded.bytes, media_type = excluded.media_type, saved_at = CASE WHEN boring_history.saved_at = 0 THEN excluded.saved_at ELSE boring_history.saved_at END', scope, path, version.revision, sequence, version.bytes, version.mediaType, version.savedAt ?? 0);
+        // A revision found again (`observed`) keeps the writer it was first recorded with; a new write of the same bytes names its writer.
+        db.run("INSERT INTO boring_history (scope, path, revision, sequence, bytes, media_type, saved_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(scope, path, revision) DO UPDATE SET sequence = excluded.sequence, bytes = excluded.bytes, media_type = excluded.media_type, saved_at = CASE WHEN boring_history.saved_at = 0 THEN excluded.saved_at ELSE boring_history.saved_at END, source = CASE WHEN excluded.source = 'observed' THEN boring_history.source ELSE excluded.source END", scope, path, version.revision, sequence, version.bytes, version.mediaType, version.savedAt ?? 0, historySource(version.source));
         db.run('DELETE FROM boring_history WHERE scope = ? AND path = ? AND revision NOT IN (SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC LIMIT ?)', scope, path, scope, path, limit);
     };
     const journal = {
@@ -107,12 +112,15 @@ export function createWorkspaceJournal(db, options = {}) {
             const row = db.get('SELECT bytes, media_type FROM boring_history WHERE scope = ? AND path = ? AND revision = ?', scope, path, revision);
             if (!row)
                 return undefined;
+            // A zero-length BLOB can come back as no bytes (see sqlite-filesystem.ts): a saved empty file is an empty version.
+            if (row.bytes === null)
+                return { revision, bytes: new Uint8Array(), mediaType: text(row.media_type) };
             if (!(row.bytes instanceof Uint8Array))
                 throw new Error('Invalid stored bytes');
             return { revision, bytes: Uint8Array.from(row.bytes), mediaType: text(row.media_type) };
         },
         revisions: (scope, path) => db.all('SELECT revision FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => text(row.revision)),
-        saves: (scope, path) => db.all('SELECT revision, saved_at FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => ({ revision: text(row.revision), savedAt: Number(row.saved_at) })),
+        saves: (scope, path) => db.all('SELECT revision, saved_at, source FROM boring_history WHERE scope = ? AND path = ? ORDER BY sequence DESC', scope, path).map(row => ({ revision: text(row.revision), savedAt: Number(row.saved_at), source: historySource(row.source) })),
     };
     registerJournalConnection(journal, db);
     return journal;

package/dist/publication-input.js

@@ -135,6 +135,12 @@ function publicationOutcome(value) {
         case 'committed': return { kind: 'committed', receipt: publicationReceipt(input.receipt) };
         case 'denied':
         case 'unavailable': return { kind: input.kind, reason: reason(input.reason) };
+        case 'file_too_large': {
+            const { path, size, limit } = input;
+            if (typeof path !== 'string' || typeof size !== 'number' || !Number.isSafeInteger(size) || typeof limit !== 'number' || !Number.isSafeInteger(limit))
+                throw new TypeError('Invalid size refusal');
+            return { kind: 'file_too_large', path, size, limit, reason: reason(input.reason) };
+        }
         case 'unknown': return { kind: 'unknown', operationId: identifier(input.operationId), reason: reason(input.reason) };
         case 'conflict': {
             if (!Array.isArray(input.current))

package/dist/revision-contracts.d.ts

@@ -24,6 +24,41 @@ export interface FileSearchRequest {
 export interface SavedRevision {
     readonly revision: string;
     readonly savedAt: number;
+    /** Who wrote it: `publish` (a conditional write), `agent` (a Pi `write` or `edit`: observed, never receipted) or `observed` (retained as found). */
+    readonly source?: 'publish' | 'agent' | 'observed';
+}
+/**
+ * One entry of a workspace's change feed (ruling 2 of 2026-10-10): an invalidation hint, never content or a receipt. Bytes and
+ * the publication journal stay authoritative; a viewer that receives one reads again.
+ *
+ * - `change`: something at `path` changed. `revision` is the Git blob id now there, or `null` when the path is absent or is a
+ *   directory (`directory: true`: something below it may have changed). `source`: `publish` (a conditional write), `agent` (a Pi
+ *   `write` or `edit`), `poll` (found by hashing, for example after a `bash` command) or `watch` (reported by the file system).
+ * - `resnapshot`: events were lost (the cursor is older than the retained window, from another provider lifetime, or the watcher
+ *   overflowed or restarted). Reload everything shown, then continue after this `seq`.
+ *
+ * `seq` increases strictly within one provider lifetime; `at` is milliseconds since the epoch.
+ */
+export type WorkspaceChangeEvent = {
+    readonly kind: 'change';
+    readonly path: string;
+    readonly revision: string | null;
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+    readonly seq: number;
+    readonly at: number;
+    readonly directory?: true;
+    readonly conversationId?: string;
+} | {
+    readonly kind: 'resnapshot';
+    readonly seq: number;
+    readonly at: number;
+};
+export interface ChangeFeedRequest {
+    /** The last `seq` already seen: only later events are delivered (a gap is a `resnapshot`). Absent: live events only. */
+    readonly since?: number | undefined;
+    /** The provider lifetime `since` came from (`ready` event). A cursor from another lifetime is a `resnapshot`, whatever its number. */
+    readonly incarnation?: string | undefined;
+    readonly signal?: AbortSignal | undefined;
 }
 export interface WorkspaceCatalog {
     readonly list: (request: FileListRequest, access: ResourceAccess) => Promise<FilePage>;
@@ -44,5 +79,11 @@ export interface RevisionProvider extends ResourceClient {
     readonly list: (request: FileListRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly search: (request: FileSearchRequest, signal?: AbortSignal) => Promise<FilePage>;
     readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+    /**
+     * The workspace's change feed (`GET ?op=changes`, server-sent events), reconnecting after the last `seq` seen until `signal`
+     * aborts; a refused binding (another workspace, revoked access) ends it with a `RevisionError`. Optional: a hand-built provider
+     * may have none, and a viewer then refreshes on its own schedule.
+     */
+    readonly changes?: (request?: ChangeFeedRequest) => AsyncIterable<WorkspaceChangeEvent>;
 }
 //# sourceMappingURL=revision-contracts.d.ts.map

package/dist/revision-handler.d.ts

@@ -1,11 +1,14 @@
 import type { ResourceAccess } from './contracts.js';
 import type { WorkspaceResourceProvider } from './workspace.js';
 export interface RevisionHandlerOptions {
+    /** The host's authentication and workspace selection, once per request. For the change feed the lease is held until the stream ends. */
     readonly resolve: (request: Request) => Promise<null | {
         readonly provider: WorkspaceResourceProvider;
         readonly access: ResourceAccess;
         readonly release?: () => void | Promise<void>;
     }>;
+    /** How often the change feed sends a comment line so proxies keep it open, in milliseconds (default 15 000). */
+    readonly heartbeatMs?: number;
 }
 export declare function createRevisionHandler(options: RevisionHandlerOptions): (request: Request) => Promise<Response>;
 //# sourceMappingURL=revision-handler.d.ts.map

package/dist/revision-handler.js

@@ -3,6 +3,90 @@ import { binding, bindingHeader, bindingValue, catalogHeader, filePage, record,
 import { guardStatus, readJsonBody, RequestGuardError } from './request-guard.js';
 import { accessSnapshot, identifier } from './publication-input.js';
 import { RevisionError } from './revision-contracts.js';
+const encoder = new TextEncoder();
+/**
+ * `GET ?op=changes[&since=<seq>&incarnation=<id>]`: the workspace's change feed as server-sent events (`event: change | resnapshot`,
+ * `id:` the seq, `data:` the JSON event), after an `event: ready` naming the current seq and the provider's incarnation, with a
+ * comment every `heartbeatMs` while idle. Plain streamed responses, so it runs on Node and on Workers alike.
+ *
+ * The stream is pull-based with no queue (`highWaterMark: 0`): the provider is read only while the client is reading, so a slow
+ * client costs the provider's bounded replay buffer (and a `resnapshot` when it falls behind), never unbounded memory here. The
+ * stream ends when the person disconnects or their access is revoked, discarding anything not yet read, and the workspace lease is
+ * released then.
+ */
+function changeStream(provider, access, request, heartbeatMs, release) {
+    const stop = new AbortController();
+    const signal = AbortSignal.any([access.signal, stop.signal, provider.lifetime]);
+    let iterator;
+    let pending;
+    let ready = false, ended = false;
+    const finish = () => {
+        if (ended)
+            return;
+        ended = true;
+        stop.abort();
+        void iterator?.return?.().catch(() => { });
+        void release();
+    };
+    const body = new ReadableStream({
+        start: controller => {
+            const close = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed or cancelled */ } };
+            signal.addEventListener('abort', close, { once: true });
+            if (signal.aborted)
+                close();
+        },
+        pull: async (controller) => {
+            if (ended)
+                return;
+            const send = (text) => { try {
+                controller.enqueue(encoder.encode(text));
+            }
+            catch {
+                finish();
+            } };
+            const end = () => { finish(); try {
+                controller.close();
+            }
+            catch { /* already closed */ } };
+            try {
+                if (!ready) {
+                    ready = true;
+                    // Without a cursor the feed starts at the current seq, which the client learns first and resumes from after a disconnect.
+                    const start = request.since ?? provider.changeHead();
+                    iterator = provider.changes({ since: start, ...(request.incarnation === undefined ? {} : { incarnation: request.incarnation }), signal }, { ...access, signal })[Symbol.asyncIterator]();
+                    // An async iterator runs its body only on the first pull, so prime it here: the watcher then starts before `ready`, and a
+                    // write the client makes after reading `ready` is not missed.
+                    pending = iterator.next();
+                    pending.catch(() => { });
+                    send(`event: ready\ndata: ${JSON.stringify({ seq: start, incarnation: provider.changeIncarnation })}\n\n`);
+                    return;
+                }
+                pending ??= iterator.next();
+                pending.catch(() => { });
+                let timer;
+                const beat = new Promise(resolve => { timer = setTimeout(() => resolve('beat'), heartbeatMs); });
+                const outcome = await Promise.race([pending, beat]).finally(() => clearTimeout(timer));
+                if (signal.aborted)
+                    return end();
+                if (outcome === 'beat')
+                    return send(': heartbeat\n\n');
+                pending = undefined;
+                if (outcome.done)
+                    return end();
+                const event = outcome.value;
+                send(`id: ${event.seq}\nevent: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`);
+            }
+            catch {
+                end(); /* the client reconnects from its last seq */
+            }
+        },
+        cancel: () => { finish(); },
+    }, { highWaterMark: 0 });
+    return new Response(body, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', 'x-accel-buffering': 'no' } });
+}
 function listRequest(value) {
     const data = record(value);
     if ((data.directory !== undefined && typeof data.directory !== 'string') || (data.cursor !== undefined && typeof data.cursor !== 'string') || (data.limit !== undefined && typeof data.limit !== 'number'))
@@ -10,6 +94,9 @@ function listRequest(value) {
     return { ...(typeof data.directory === 'string' ? { directory: data.directory } : {}), ...(typeof data.cursor === 'string' ? { cursor: data.cursor } : {}), ...(typeof data.limit === 'number' ? { limit: data.limit } : {}) };
 }
 export function createRevisionHandler(options) {
+    const heartbeatMs = options.heartbeatMs ?? 15_000;
+    if (!Number.isSafeInteger(heartbeatMs) || heartbeatMs < 1)
+        throw new RangeError('The heartbeat interval must be a positive integer');
     return async (request) => {
         let release;
         const operations = new Set();
@@ -34,7 +121,8 @@ export function createRevisionHandler(options) {
                 return refuse(403);
             const association = binding({ identity: captured, workspace: selected.provider.identity });
             const respond = (value) => Response.json(value, { headers: { 'cache-control': 'no-store' } });
-            if (request.method === 'GET')
+            const op = new URL(request.url).searchParams.get('op');
+            if (request.method === 'GET' && op === null)
                 return respond(association);
             const header = request.headers.get(bindingHeader);
             if (!header || header.length > 16384)
@@ -49,6 +137,26 @@ export function createRevisionHandler(options) {
             if (requested !== bindingValue(association))
                 return refuse(409);
             const provider = selected.provider;
+            if (request.method === 'GET') {
+                if (op !== 'changes')
+                    return refuse(400);
+                const cursor = new URL(request.url).searchParams.get('since');
+                if (cursor !== null && !/^\d{1,16}$/.test(cursor))
+                    return refuse(400);
+                const since = cursor === null ? undefined : Number(cursor);
+                const incarnation = new URL(request.url).searchParams.get('incarnation') ?? undefined;
+                if (incarnation !== undefined && !/^[\w-]{1,64}$/.test(incarnation))
+                    return refuse(400);
+                if (since !== undefined && !Number.isSafeInteger(since))
+                    return refuse(400);
+                // The stream owns the lease from here: it is released when the stream ends, not when this function returns.
+                const lease = release;
+                release = undefined;
+                return changeStream(provider, access, { since, incarnation }, heartbeatMs, async () => { try {
+                    await lease?.();
+                }
+                catch { /* the stream already ended */ } });
+            }
             if (!request.headers.has(catalogHeader))
                 return await createResourceHandler({
                     authenticate: async () => access,

package/dist/revision-protocol.d.ts

@@ -1,6 +1,6 @@
 import type { ResourceIdentity } from './remote-protocol.js';
 import type { WorkspaceKey } from './workspace.js';
-import type { FilePage, SavedRevision } from './revision-contracts.js';
+import type { FilePage, SavedRevision, WorkspaceChangeEvent } from './revision-contracts.js';
 export declare const bindingHeader = "x-boring-workspace";
 export declare const catalogHeader = "x-boring-catalog";
 export interface RevisionBinding {
@@ -12,4 +12,11 @@ export declare function binding(value: unknown): RevisionBinding;
 export declare const bindingValue: (value: RevisionBinding) => string;
 export declare function filePage(value: unknown): FilePage;
 export declare function savedRevisions(value: unknown): readonly SavedRevision[];
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export declare function changeEvent(value: unknown): WorkspaceChangeEvent;
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export declare function serverEvents(body: ReadableStream<Uint8Array>, limit?: number): AsyncGenerator<{
+    readonly event: string;
+    readonly data: string;
+}>;
 //# sourceMappingURL=revision-protocol.d.ts.map

package/dist/revision-protocol.js

@@ -37,6 +37,70 @@ export function savedRevisions(value) {
         const entry = record(item);
         if (typeof entry.savedAt !== 'number' || !Number.isSafeInteger(entry.savedAt) || entry.savedAt < 0)
             throw new RevisionError('invalid', 'Invalid save timestamp');
-        return { revision: identifier(entry.revision), savedAt: entry.savedAt };
+        const source = entry.source === 'publish' || entry.source === 'agent' || entry.source === 'observed' ? entry.source : undefined;
+        return { revision: identifier(entry.revision), savedAt: entry.savedAt, ...(source ? { source } : {}) };
     });
 }
+const sources = new Set(['publish', 'agent', 'poll', 'watch']);
+const sequence = (value, what) => {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        throw new RevisionError('invalid', `Invalid ${what}`);
+    return value;
+};
+/** One change-feed event as the server sent it, checked field by field (`data:` of `event: change | resnapshot`). */
+export function changeEvent(value) {
+    const data = record(value);
+    const seq = sequence(data.seq, 'change sequence'), at = sequence(data.at, 'change time');
+    if (data.kind === 'resnapshot')
+        return { kind: 'resnapshot', seq, at };
+    if (data.kind !== 'change' || typeof data.path !== 'string' || typeof data.source !== 'string' || !sources.has(data.source))
+        throw new RevisionError('invalid', 'Invalid change event');
+    if (data.directory !== undefined && data.directory !== true)
+        throw new RevisionError('invalid', 'Invalid change event');
+    const path = data.path === '' && data.directory === true ? '' : catalogPath(data.path);
+    const revision = data.revision === null ? null : identifier(data.revision);
+    return {
+        kind: 'change', path, revision, source: data.source, seq, at,
+        ...(data.directory === true ? { directory: true } : {}),
+        ...(data.conversationId !== undefined ? { conversationId: identifier(data.conversationId) } : {}),
+    };
+}
+/** Server-sent events from a response body: `{ event, data }` per message, comments skipped, a line longer than `limit` refused. */
+export async function* serverEvents(body, limit = 1_048_576) {
+    const reader = body.getReader(), decoder = new TextDecoder();
+    let pending = '', event = 'message', data = [];
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            pending += decoder.decode(value, { stream: true });
+            let newline;
+            while ((newline = pending.search(/\r?\n/)) !== -1) {
+                const line = pending.slice(0, newline);
+                pending = pending.slice(pending[newline] === '\r' ? newline + 2 : newline + 1);
+                if (line === '') {
+                    if (data.length)
+                        yield { event, data: data.join('\n') };
+                    event = 'message';
+                    data = [];
+                    continue;
+                }
+                if (line.startsWith(':'))
+                    continue;
+                const colon = line.indexOf(':');
+                const field = colon === -1 ? line : line.slice(0, colon);
+                const content = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                if (field === 'event')
+                    event = content;
+                else if (field === 'data')
+                    data.push(content);
+            }
+            if (pending.length > limit)
+                throw new RevisionError('invalid', 'Change feed line exceeds the limit');
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}