@hachej/boring-files 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Hurault
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @hachej/boring-files
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Versioned resources over a workspace's files: the contracts, and the workspace provider over Pi's own FileSystem (no Boring file system). Reader, publisher and lookup capabilities are independently injectable; the aggregate ResourceProvider advertises actual support/grants/availability/qualified guarantees. ResourceClient carries browser intent, not trusted host ResourceAccess.
+
+Publication requires nonempty changes and explicit atomicity. The trusted boundary computes the canonical digest and checks approval; those are not client-authored authority fields. Receipts identify valid create/replace/delete transitions; partial outcomes retain operation, input index and full target/view. Reconciliation is optional and required explicitly where claimed; not-found is not proof of no effect.
+
+Opaque resource view IDs are provider-scoped and bound to the actual backing/incarnation by the provider. Import contracts with `import type`.
+
+`@hachej/boring-files/workspace` exports `createWorkspaceProvider({ identity, fs, journal })`: the one provider of a workspace's files ([One place for files](../../docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)). It takes a Pi `FileSystem` (a disk environment, the virtual workspace or the SQLite backend below), the host's workspace identity and a journal (`createWorkspaceJournal(connection)` from `@hachej/boring-files/journal`, receipts, intents and the last 20 versions of each file in SQLite). Revisions are Git blob ids of the bytes. A conditional write checks every expected revision and precondition inside the workspace's queue, records its intent first and its receipt last; an intent without a completion looks up as `unknown` and is never replayed. Its owner closes the connection; the provider borrows it. Node currently marks `node:sqlite` experimental.
+
+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.
+
+`@hachej/boring-files/sqlite` exports `openNodeConnection(filename, settings?)` (a `node:sqlite` file as a `SqliteConnection`) and `openNodeDatabase(filename, settings?)` (the configured `DatabaseSync`, for Pi's public adapter: `SqliteStorage.open(new NodeSqliteDatabase(openNodeDatabase(file, settings)))`). `settings` is `SqliteSettings` `{ journalMode?: 'wal' | 'delete' | 'truncate' | 'persist', lockingMode?: 'normal' | 'exclusive', busyTimeoutMs?, synchronous?: 'off' | 'normal' | 'full' | 'extra', tempStore?: 'default' | 'file' | 'memory' }`; missing fields come from `sqliteSettings.localDisk` (WAL, normal locking, 5 s busy timeout, full sync: the behaviour before settings existed). `sqliteSettings.networkFilesystem` is for one process owning a file on NFS such as EFS: rollback journal, `exclusive` locking with the lock taken at open, 10 s busy timeout, full sync, temporary tables in memory; another connection to that file fails with `SqliteLockedError` (`code: 'sqlite-locked'`) after its busy timeout. Names and values are allow-listed (`TypeError` otherwise, before the file is opened); there is no free-form pragma. The settings live in `@hachej/boring-files/sqlite-settings` (pure, browser-safe; `sqlitePragmas(settings)` is what the browser's SQLite Wasm uses), and `npm run check` refuses `PRAGMA journal_mode`/`locking_mode` assignments anywhere else. The journal, the metering ledger and the SQLite file system borrow a connection and never set pragmas.
+
+`@hachej/boring-files/sqlite-filesystem` exports `openSqliteFileSystem({ connection, workspace, cwd })`: a Pi `FileSystem` whose regular files and directories are rows of one workspace in a `SqliteConnection` (`openNodeConnection`, `durableObjectSqliteConnection`, or `openBrowserSqliteConnection` from the private, unpublished `@hachej/boring-browser/sqlite`, available only inside this monorepo), with the `incarnation` of those rows. Like Pi's `NodeExecutionEnv` (which Pi's `write` tool relies on), `writeFile` creates missing parent directories; a parent that is a file still fails. Given to `createWorkspaceProvider` it is the SQLite workspace backend ([One place for files](../../docs/architecture/FILES-GIT-EXEC.md#one-place-for-files)): multi-file conditional batches commit in one transaction, together with the receipt when the journal uses the same connection. It implements Pi 1.1's full `FileSystem` (positional readers whose `scanLines` is Pi's own `LineScanner`, paged directory readers, and a polling `watch`) and answers with Pi's own `FileError`s, so this entry loads `@earendil-works/pi-durable/env` (Pi's portable contracts, no engine): install `@earendil-works/pi-durable` with it. The other entries of this package do not need Pi.
+
+See [scaffold guide](../../docs/contracts/SCAFFOLD.md) and [resource design](../../docs/architecture/FILES-GIT-EXEC.md).
+
+## Node hosts
+
+`@hachej/boring-files/node-http` bridges `node:http` to the Fetch handlers of these packages: `webRequest(incoming, url, { signal, maxBytes })` reads the body first under a byte cap (never `Readable.toWeb` on a live request, whose cancellation kills the process) and `sendWebResponse(response, outgoing, { signal })` flushes the headers at once, keeps each `set-cookie`, waits for `drain` when the socket is full and cancels the web body when the client disconnects. The example servers use it; `npm run check` refuses hand-written response copies under `examples/`.
+
+## Optional authenticated resource transport
+
+`@hachej/boring-files/remote` exports `createResourceClient` and `createResourceHandler`. Both are Fetch adapters over the existing resource contracts. They import no Pi runtime, filesystem or database. The client implements `ResourceClient`; `publication: true` and `reconciliation: true` independently select its optional methods. The handler borrows a reader, optional publisher and optional lookup. It never closes them.
+
+```ts
+const handler = createResourceHandler({
+  authenticate: request => host.authenticateResourceRequest(request),
+  reader: provider,
+  publisher: provider.publication,
+  lookup: provider.reconciliation,
+});
+const client = createResourceClient({
+  identity: { principalId, scopeId, initiatorId },
+  endpoint: 'https://example.invalid/resources',
+  fetch: authenticatedFetch,
+  publication: true,
+  reconciliation: true,
+});
+```
+
+`publication: true` requires `reconciliation: true` (types and constructor): a save whose acknowledgement is lost is `unknown`, and only a lookup can resolve it. A read-only client sets neither.
+
+Authentication returns trusted `ResourceAccess` or null. Its optional signal represents host revocation; the handler combines it with request cancellation. Client identity is expected response metadata, never authority. The host owns credentials, origin/CSRF/CORS policy, endpoint routing and provider confinement. The injected Fetch must honor `redirect: 'error'`, preserve cancellation and never retry effects. Bind a handler to the host's selected provider capabilities. Browser JSON cannot grant access or supply a trusted digest or approval.
+
+The private versioned JSON envelope captures publication bytes before any asynchronous work. Protocol version 2 carries bytes as canonical base64 text (version 1 integer arrays are refused). Default limits are 4 MiB per serialized request and 8 MiB per serialized response, configurable up to 64 MiB. Incoming bodies use a bounded growing buffer. These are accepted-message limits, not limits on Fetch allocation, provider output, local request capture, JSON expansion or digest memory. Hosts must bound their trusted inputs and provider production separately.
+
+All-or-nothing receipts must match the captured operation, canonical digest, actor and complete target transitions. Receipt order is preserved but does not determine association. Per-change requests are refused before dispatch; partial acknowledgements are unqualified and become unknown. A real partial provider must establish its receipt convention before that transport guarantee is added.
+
+Transport errors, mismatched or oversized acknowledgements and aborted observation produce unknown publication/lookup outcomes. They never manufacture a known-no-commit denial or provider not-found, and never trigger replay. Read transport failures produce unavailable. Lookup checks operation and actor association; the caller still checks the digest and transitions against its captured original attempt. An operation ID alone cannot establish those arguments. Not-found does not authorize replay.
+
+Revocation suppresses disclosure until the handler constructs its response; already delivered bytes cannot be retracted. Aborting observation does not prove provider termination, rollback or an atomic revocation fence. Provider exceptions and response serialization failures may follow a commit, so the client retains uncertainty. The workspace provider's declared guarantees remain unchanged.
+
+Run `node examples/resource-transport.mjs` for a fictional exact-save and lookup journey through real Request/Response objects. Public-output tests also compose a native ToolTask and lost-acknowledgement Markdown reconciliation. The isolated document consumer exercises this adapter with strict types and a browser bundle without Pi, agent or React installed. These checks do not qualify deployed HTTP, browser identity policy or remote provider lifecycle.
+
+`@hachej/boring-files/text` supplies the shared pure `applyTextEdits` transform and input parser. Edits run in order, require unique nonempty exact matches and preserve untouched whitespace. A failed edit refuses the whole transformation. It performs no I/O and grants no permission.
+
+## Optional working Git
+
+`@hachej/boring-files/git` requires pinned `isomorphic-git@1.42.6`. `createGitRepository` borrows its public `PromiseFsClient`, an absolute normalized directory, a host author and a current `authorize(operation)` callback. The callback grants the bound caller access to the entire selected repository, including worktree and metadata. Only exact `true` grants access. It runs after queue acquisition and again before returning results. Share one repository instance across callers. Its queue serializes those calls only; other instances, raw filesystem writers and aliases require underlying host policy. Relative argument validation does not confine an unrestricted filesystem or symlink targets.
+
+`createEnvGitFs(fileSystem, context)` is the `PromiseFsClient` over a Pi `FileSystem` (an `ExecutionEnv`'s files): every Git read and write goes through that environment, so its confinement applies to Git too. Files read as mode `0o100644` (Pi's file contract has no modes) and symbolic links are refused (`ENOSYS`), never followed.
+
+Methods are `init`, matrix `status`, `add`, index-only `remove`, `commit`, twenty-entry `log`, `branches`, `branch`, `checkout` and `diff`. Diff compares exact tree refs/object IDs, index and worktree. It returns changed blob paths, modes, object IDs and byte arrays, including untracked worktree files. It excludes `.git`, rejects unsupported entry types and reports limit errors without truncated success. Default returned-content limits are 100 files and 1 MiB. Traversal is serial, but upstream can allocate an entire blob before the byte limit is checked. These limits do not bound peak memory or repository traversal cost. Status and worktree diff disable native index refresh.
+
+The host owns filesystem confinement, credentials and disposal. No network transport is installed. Cancellation is checked around native operations and during diff traversal; it cannot roll back Git mutations. `GitOperationError.effects` distinguishes pre-execution refusal from possible prior mutation. Git operations have no durable operation receipts, conditional publication or crash recovery guarantee.
+
+
+### Local publication preparation failures
+
+`PublicationNotDispatchedError` from `@hachej/boring-files/publication` identifies a valid publication request that the remote client could not dispatch. Its `operationId` identifies that invocation. Local byte-limit, unsupported atomicity, digest, request-construction and pre-dispatch cancellation failures use this error. The error does not establish the outcome of earlier attempts with the same operation ID. Retain and reconcile any earlier uncertain attempt.
+
+Once the fetch callback is called, transport exceptions, HTTP errors and invalid acknowledgements remain `unknown`, including a callback that throws the same error class after committing. A lookup `not-found` still does not prove that an interrupted request had no effect. The text controllers use the typed error only for their freshly generated operation, releasing that attempt so the user can save a corrected draft.
+
+SQLite reads and receipt lookups of the SQLite workspace backend use deferred read transactions; a conditional write keeps its `BEGIN IMMEDIATE` transaction for its files and receipt. Tests hold an independent WAL writer transaction and read the previous committed file and receipt through the provider. This qualifies that WAL contention case; opening the database and arbitrary SQLite locking modes can still require write access or wait.
+
+## Migrating from the removed resource store
+
+The SQLite resource store of `@hachej/boring-files/sqlite` (`openSqliteResources`, `SqliteResourceProvider` and its option types) is
+removed. Its documents become files of a workspace; `SqliteConnection` and `openNodeConnection` stay in `@hachej/boring-files/sqlite`.
+A host that kept one store with rows per scope (the redaction and current-hub fixtures here) opens one SQLite-backed workspace per
+scope in the same database:
+
+| Old call | New call |
+| --- | --- |
+| `openSqliteResources({ filename, providerId, authorize })` | `connection = openNodeConnection(filename)`, `journal = createWorkspaceJournal(connection)`, then per scope `fs = openSqliteFileSystem({ connection, workspace: scopeId, cwd: '/workspace' })` and `createWorkspaceProvider({ identity: { providerId, instanceId: scopeId, incarnation: fs.incarnation, viewId: 'published' }, fs, journal })` |
+| `openSqliteResources({ connection, ... })` (a Durable Object) | the same calls with `durableObjectSqliteConnection(ctx.storage)` from `@hachej/boring-files/sqlite-durable-object` |
+| `authorize(action, target, access)` inside the store | the host checks its policy before calling the workspace's provider; [`examples/shared/sqlite-workspaces.mjs`](../../examples/shared/sqlite-workspaces.mjs) shows one way (a refused write whose operation committed and a refused lookup read `unknown`) |
+| `provider.close()` | `connection.close()` by the connection's owner |
+| a `delete` change | the workspace's own file tools (`fs.remove`, Pi's `bash`); publication refuses deletes |
+| revisions were random ids; saving the same bytes made a new revision | revisions are Git blob ids: the same bytes keep their revision, and `before` equal to `after` is a valid committed change |
+| every revision retained | the last 20 versions per file (`createWorkspaceJournal(connection, { historyLimit })`); older ones read `unavailable` |
+
+Existing store databases are not migrated: their `boring_documents` rows are not read by the workspace backend. Copy each current
+document into its workspace with a create, or start from the files.
+
+## Frontend revision provider
+
+`@hachej/boring-files/revision-handler` serves an existing workspace provider. The
+host resolves its OAuth session and selected workspace on every request:
+
+```ts
+const handleFiles = createRevisionHandler({
+  resolve: async request => {
+    const session = await authenticate(request);
+    if (!session) return null;
+    return {
+      provider: workspaces.workspace(session.workspaceId),
+      access: {
+        principalId: session.userId,
+        scopeId: session.workspaceId,
+        initiatorId: session.userId,
+      },
+    };
+  },
+});
+```
+
+`authenticate` and `workspaces` are host objects. Import `createRevisionHandler`
+from `@hachej/boring-files/revision-handler`. If acquisition returns a lease,
+include `release`; the handler retains it until underlying operations settle,
+including after request cancellation.
+
+In the browser, import `connectRevisionProvider` from
+`@hachej/boring-files/revision` and connect once per selected workspace:
+
+```ts
+const revisionProvider = await connectRevisionProvider({
+  endpoint: new URL('/api/workspace', location.origin),
+  fetch: request => fetch(request),
+});
+```
+
+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`, `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.
+
+Catalog defaults hide Git-ignored files, dependency/build folders and internal
+metadata. Configure `createWorkspaceProvider({ ..., catalog: { defaults: false,
+filter: entry => ... } })` to override them. Filters govern presentation, not
+access control. The host authorizes the whole selected workspace. Listings do
+not follow symlinks. Pagination is a live, lexical view, not a frozen snapshot;
+refresh after concurrent changes. Traversal over the configured `maxEntries`
+(default 100,000) fails explicitly. History contains revisions retained by the
+workspace journal, not Git commits or an imported filesystem's prior history.
+
+The existing resource transport limits still apply: requests default to 4 MiB
+and responses to 8 MiB, including their serialized envelope. This API does not
+provide streaming uploads.
+
+### Durable Object apps
+
+A Cloudflare Durable Object keeps its workspace in its own SQLite storage, and the Library binds to it the same way as a Node host. Each
+piece is the one the Node example uses, with `durableObjectSqliteConnection(ctx.storage)` from
+`@hachej/boring-files/sqlite-durable-object` in place of `openNodeConnection`. The workspace and its journal share that one connection,
+so a multi-file save and its receipt commit in one `transactionSync`:
+
+```ts
+import { durableObjectSqliteConnection } from '@hachej/boring-files/sqlite-durable-object';
+import { openSqliteFileSystem } from '@hachej/boring-files/sqlite-filesystem';
+import { createWorkspaceJournal } from '@hachej/boring-files/journal';
+import { createWorkspaceProvider } from '@hachej/boring-files/workspace';
+import { createRevisionHandler } from '@hachej/boring-files/revision-handler';
+
+// In the object's constructor: one connection and journal, one provider per workspace the object serves.
+const connection = durableObjectSqliteConnection(this.ctx.storage);
+const journal = createWorkspaceJournal(connection);
+const fs = openSqliteFileSystem({ connection, workspace: workspaceId, cwd: '/workspace' });
+const provider = createWorkspaceProvider({
+  identity: { providerId: 'files', instanceId: workspaceId, incarnation: fs.incarnation, viewId: 'published' },
+  fs,
+  journal,
+});
+
+// The object's HTTP route: the host authenticates the request and picks the workspace it selected.
+const handleFiles = createRevisionHandler({
+  resolve: async request => {
+    const session = await authenticate(request);
+    if (!session) return null;
+    return { provider: this.providerFor(session.workspaceId), access: { principalId: session.userId, scopeId: session.workspaceId, initiatorId: session.userId } };
+  },
+});
+```
+
+`history` is the journal's retained revisions for each file, newest first, with `savedAt` in milliseconds; a save made before this
+journal recorded times reports `savedAt: 0`. The browser connects as in the Node case: `connectRevisionProvider({ endpoint, fetch })`
+from `@hachej/boring-files/revision`. Each scope is its own workspace (rows keyed by `workspace`), so a request is served only from the
+provider its `resolve` returns.

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import type { ResourceRead, ReadResult, PublicationRequest, PublicationResult, PublicationLookupResult } from './contracts.js';
+/** Authenticated host/client binding. No ResourceAccess, approval authority or
+ * trusted request digest is accepted from the browser. A request still requires
+ * real server validation. Uncertain saves can use optional reconciliation.
+ */
+export interface ResourceClient {
+    readonly read: (request: ResourceRead, signal?: AbortSignal) => Promise<ReadResult>;
+    /** PublicationNotDispatchedError describes this call only; reconcile any earlier uncertain attempt separately. */
+    readonly publish?: (request: PublicationRequest, signal?: AbortSignal) => Promise<PublicationResult>;
+    readonly lookup?: (operationId: string, signal?: AbortSignal) => Promise<PublicationLookupResult>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts.d.ts

@@ -0,0 +1,194 @@
+/** Application resource/publication contracts, not Pi working-filesystem
+ * methods. Types constrain shape; host authorization and provider guarantees
+ * still require runtime validation and qualification.
+ */
+export type NonEmpty<Value> = readonly [Value, ...Value[]];
+export interface ResourceId {
+    readonly providerId: string;
+    readonly path: string;
+}
+export type ResourceView = {
+    readonly kind: 'published';
+} | {
+    readonly kind: 'working';
+    /** Opaque provider-scoped view identity. The provider binds it to the
+     * actual backing/incarnation; never reuse it for a different view.
+     * A resource view need not be a native workspace or remote machine.
+     */
+    readonly viewId: string;
+};
+export interface ResourceLocator {
+    readonly resource: ResourceId;
+    readonly view: ResourceView;
+}
+export interface ResourceRef extends ResourceLocator {
+    readonly revision: string;
+}
+export interface ResourceRead {
+    readonly target: ResourceLocator;
+    readonly revision: {
+        readonly kind: 'latest';
+    } | {
+        readonly kind: 'exact';
+        readonly value: string;
+    };
+}
+/** Trusted server context, never model/browser request authority. */
+export interface ResourceAccess {
+    readonly principalId: string;
+    readonly scopeId: string;
+    readonly initiatorId: string;
+    readonly signal?: AbortSignal;
+    /** Host-resolved approval/policy binding, not a caller-provided grant. */
+    readonly authorizationRef?: string;
+}
+export interface ResourceSnapshot {
+    readonly ref: ResourceRef;
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+}
+export type ReadResult = {
+    readonly kind: 'available';
+    readonly snapshot: ResourceSnapshot;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'denied';
+    readonly reason: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/** Reused for publication dependencies and a new/existing editor's save base. */
+export type ResourceExpectation = {
+    readonly kind: 'absent';
+    readonly target: ResourceLocator;
+} | {
+    readonly kind: 'revision';
+    readonly target: ResourceRef;
+};
+export type ResourceChange = {
+    readonly kind: 'create';
+    readonly target: ResourceLocator;
+    readonly expected: {
+        readonly kind: 'absent';
+    };
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+} | {
+    readonly kind: 'replace';
+    readonly target: ResourceRef;
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+} | {
+    readonly kind: 'delete';
+    readonly target: ResourceRef;
+};
+/** Caller expresses intent. The trusted boundary snapshots mutable bytes,
+ * validates the request and computes its canonical digest; the caller cannot
+ * assert that two different payloads have the same trusted digest.
+ */
+export interface PublicationRequest {
+    readonly operationId: string;
+    readonly changes: NonEmpty<ResourceChange>;
+    readonly atomicity: 'all-or-nothing' | 'per-change';
+    /** Extra exact-content/absence dependencies, in addition to change targets.
+     * Search/listing predicate evidence needs its separately qualified provider
+     * integration; this minimal contract does not pretend to implement it.
+     */
+    readonly preconditions?: readonly ResourceExpectation[];
+}
+export type CommittedChange = {
+    readonly kind: 'create';
+    readonly before: null;
+    readonly after: ResourceRef;
+} | {
+    readonly kind: 'replace';
+    readonly before: ResourceRef;
+    readonly after: ResourceRef;
+} | {
+    readonly kind: 'delete';
+    readonly before: ResourceRef;
+    readonly after: null;
+};
+export interface PublicationReceipt {
+    readonly operationId: string;
+    /** Computed/checked by the trusted boundary, retained for reconciliation. */
+    readonly argumentDigest: string;
+    readonly principalId: string;
+    readonly scopeId: string;
+    readonly initiatorId: string;
+    readonly changes: NonEmpty<CommittedChange>;
+    readonly evidenceRef: string;
+}
+/** These are known no-commit refusals, not substitutes for an uncertain effect. */
+export type PublicationRefusal = {
+    readonly kind: 'conflict';
+    readonly current: readonly ResourceRef[];
+    readonly reason: string;
+} | {
+    readonly kind: 'denied';
+    readonly reason: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export type PublicationOutcome = {
+    readonly kind: 'committed';
+    readonly receipt: PublicationReceipt;
+} | PublicationRefusal | {
+    readonly kind: 'unknown';
+    readonly operationId: string;
+    readonly reason: string;
+};
+/** Result association survives multiple changes/views and lost responses.
+ * Providers validate index coverage/uniqueness and target/receipt agreement.
+ */
+export interface PublicationItem {
+    readonly changeIndex: number;
+    readonly target: ResourceLocator;
+    readonly outcome: PublicationOutcome;
+}
+export type PublicationResult = PublicationOutcome | {
+    readonly kind: 'partial';
+    readonly operationId: string;
+    readonly items: NonEmpty<PublicationItem>;
+};
+export interface ProviderGuarantees {
+    readonly pinnedReads: boolean;
+    readonly conditionalPublication: boolean;
+    readonly atomicMutationAndReceipt: boolean;
+    readonly atomicBatch: boolean;
+    readonly operationLookup: boolean;
+    readonly revocationFencing: boolean;
+}
+export interface ResourceCapabilities {
+    readonly supported: readonly ('read' | 'create' | 'replace' | 'delete' | 'lookup')[];
+    readonly effective: readonly ('read' | 'create' | 'replace' | 'delete' | 'lookup')[];
+    readonly availability: 'available' | 'unavailable' | 'unknown';
+    readonly observedAt: string;
+    readonly guarantees: ProviderGuarantees;
+}
+/** Independently injectable read, publication and reconciliation capabilities. */
+export interface ResourceReader {
+    readonly read: (request: ResourceRead, access: ResourceAccess) => Promise<ReadResult>;
+}
+export interface ResourcePublisher {
+    readonly publish: (request: PublicationRequest, access: ResourceAccess) => Promise<PublicationResult>;
+}
+export type PublicationLookupResult = PublicationResult | {
+    readonly kind: 'not-found';
+};
+export interface PublicationLookup {
+    /** Namespace includes the trusted caller/scope. Not-found means no retained
+     * receipt, not proof that a timed-out operation had no effect. No blind retry.
+     */
+    readonly lookup: (operationId: string, access: ResourceAccess) => Promise<PublicationLookupResult>;
+}
+export interface ResourceProvider extends ResourceReader {
+    readonly providerId: string;
+    readonly capabilities: (target: ResourceLocator, access: ResourceAccess) => Promise<ResourceCapabilities>;
+    readonly publication?: ResourcePublisher;
+    readonly reconciliation?: PublicationLookup;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/git.d.ts

@@ -0,0 +1,105 @@
+import git from 'isomorphic-git';
+import type { PromiseFsClient } from 'isomorphic-git';
+import type { Context } from '@earendil-works/chord';
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+export type GitOperation = 'init' | 'status' | 'add' | 'remove' | 'commit' | 'log' | 'branches' | 'branch' | 'checkout' | 'diff';
+export type GitView = {
+    readonly kind: 'tree';
+    readonly ref: string;
+} | {
+    readonly kind: 'index';
+} | {
+    readonly kind: 'worktree';
+};
+export interface GitFileVersion {
+    readonly oid: string;
+    readonly mode: number;
+    readonly bytes: Uint8Array;
+}
+export interface GitFileChange {
+    readonly path: string;
+    readonly before: GitFileVersion | null;
+    readonly after: GitFileVersion | null;
+}
+export interface GitRepositoryOptions<FS extends PromiseFsClient> {
+    readonly fs: FS;
+    readonly directory: string;
+    readonly author: NonNullable<Parameters<typeof git.commit>[0]['author']>;
+    /** A current repository-wide grant for the host-bound caller, including all worktree and Git metadata. */
+    readonly authorize: (operation: GitOperation) => boolean | Promise<boolean>;
+    /** Returned diff limits. Upstream may allocate an entire blob before its size is checked. */
+    readonly diffLimits?: {
+        readonly files: number;
+        readonly bytes: number;
+    };
+}
+export declare class GitOperationError extends Error {
+    readonly effects: 'none' | 'possible';
+    constructor(message: string, effects: 'none' | 'possible', options?: ErrorOptions);
+}
+/** Borrow one filesystem and share this instance across callers. Raw filesystem writers do not take this queue. */
+export declare function createGitRepository<FS extends PromiseFsClient>(options: GitRepositoryOptions<FS>): Readonly<{
+    fs: FS;
+    directory: string;
+    init: (signal?: AbortSignal) => Promise<void>;
+    status: (signal?: AbortSignal) => Promise<git.StatusRow[]>;
+    add: (path: string, signal?: AbortSignal) => Promise<void>;
+    remove: (path: string, signal?: AbortSignal) => Promise<void>;
+    commit: (message: string, signal?: AbortSignal) => Promise<string>;
+    log: (signal?: AbortSignal) => Promise<git.ReadCommitResult[]>;
+    branches: (signal?: AbortSignal) => Promise<string[]>;
+    branch: (ref: string, signal?: AbortSignal) => Promise<void>;
+    checkout: (ref: string, signal?: AbortSignal) => Promise<void>;
+    diff: (before: GitView, after: GitView, signal?: AbortSignal) => Promise<GitFileChange[]>;
+}>;
+export type GitRepository = ReturnType<typeof createGitRepository>;
+/**
+ * isomorphic-git I/O over a Pi `FileSystem` (an `ExecutionEnv`'s files): every read and write goes through that environment, so its
+ * confinement (for example the AWS adapter's folder and symbolic link checks) also confines Git. No second checkout, no native Git.
+ * Modes are not part of Pi's file contract: files read as 0o100644. Symbolic links are refused (`ENOSYS`): Git fails on a worktree
+ * that contains one rather than following it.
+ */
+export declare function createEnvGitFs(filesystem: FileSystem, context: Context): {
+    promises: {
+        readFile: (path: string, options?: string | {
+            encoding?: string;
+        }) => Promise<string | Uint8Array<ArrayBufferLike>>;
+        writeFile: (path: string, bytes: string | Uint8Array) => Promise<void>;
+        unlink: (path: string) => Promise<void>;
+        readdir: (path: string) => Promise<string[]>;
+        mkdir: (path: string) => Promise<void>;
+        rmdir: (path: string) => Promise<void>;
+        stat: (path: string) => Promise<{
+            type: string;
+            mode: number;
+            size: number;
+            mtimeMs: number;
+            ctimeMs: number;
+            uid: number;
+            gid: number;
+            dev: number;
+            ino: number;
+            isFile: () => boolean;
+            isDirectory: () => boolean;
+            isSymbolicLink: () => boolean;
+        }>;
+        lstat: (path: string) => Promise<{
+            type: string;
+            mode: number;
+            size: number;
+            mtimeMs: number;
+            ctimeMs: number;
+            uid: number;
+            gid: number;
+            dev: number;
+            ino: number;
+            isFile: () => boolean;
+            isDirectory: () => boolean;
+            isSymbolicLink: () => boolean;
+        }>;
+        readlink: (path: string) => Promise<never>;
+        symlink: (_target: string, path: string) => Promise<never>;
+        chmod: () => Promise<void>;
+    };
+};
+//# sourceMappingURL=git.d.ts.map