@feltdb/core 0.9.1 → 0.11.0

package/dist/file-db.js

@@ -53,6 +53,7 @@ export class FileJsDb {
     }
     loadState() {
         const nodeFs = getFsSync();
+        const backupPath = `${this.statePath}.backup`;
         // Load atomic snapshot if it exists
         if (nodeFs.existsSync(this.statePath)) {
             try {
@@ -60,8 +61,15 @@ export class FileJsDb {
                 const snapshot = JSON.parse(content);
                 // Validate snapshot structure
                 if (snapshot.version !== 1 || !snapshot.meta || !snapshot.rows || !snapshot.events) {
-                    console.warn(`Invalid snapshot structure at ${this.statePath}, reinitializing`);
-                    return this.initializeState();
+                    console.warn(`Invalid snapshot structure at ${this.statePath}, attempting backup recovery`);
+                    return this.loadStateFromBackup();
+                }
+                // Successfully loaded valid state, preserve it as backup
+                try {
+                    nodeFs.copyFileSync(this.statePath, backupPath);
+                }
+                catch {
+                    // Backup failure is non-fatal
                 }
                 return {
                     version: snapshot.version,
@@ -75,12 +83,41 @@ export class FileJsDb {
                 };
             }
             catch (error) {
-                console.warn(`Failed to load snapshot from ${this.statePath}, reinitializing: ${error}`);
-                return this.initializeState();
+                console.warn(`Failed to load snapshot from ${this.statePath}: ${error}`);
+                console.warn(`Attempting to recover from backup...`);
+                return this.loadStateFromBackup();
             }
         }
         return this.initializeState();
     }
+    loadStateFromBackup() {
+        const nodeFs = getFsSync();
+        const backupPath = `${this.statePath}.backup`;
+        if (nodeFs.existsSync(backupPath)) {
+            try {
+                const content = nodeFs.readFileSync(backupPath, 'utf-8');
+                const snapshot = JSON.parse(content);
+                if (snapshot.version === 1 && snapshot.meta && snapshot.rows && snapshot.events) {
+                    console.warn(`Recovered state from backup at ${backupPath}`);
+                    return {
+                        version: snapshot.version,
+                        instance_id: this.origin,
+                        sequence: snapshot.meta.sequence,
+                        rows: snapshot.rows,
+                        events: snapshot.events,
+                        peers: snapshot.meta.peers ?? [],
+                        sequences: snapshot.meta.sequences ?? {},
+                        applied_transactions: snapshot.applied_transactions ?? []
+                    };
+                }
+            }
+            catch {
+                // Backup is also corrupted or invalid
+            }
+        }
+        console.warn(`Backup recovery failed, reinitializing state`);
+        return this.initializeState();
+    }
     initializeState() {
         return {
             version: 1,
@@ -333,7 +370,11 @@ export class FileJsDb {
             if (plan.kind === 'reject')
                 throw new EmbeddedTransactionRejected(plan.reason, plan.failure);
             // Build the post-transaction state without touching the live one.
-            const rows = { ...this.state.rows };
+            // Critical: Deep-copy rows to prevent stale references after refresh
+            const rows = {};
+            for (const [key, value] of Object.entries(this.state.rows)) {
+                rows[key] = value;
+            }
             const events = [...this.state.events];
             let sequence = this.state.sequence;
             const timestamp = Date.now();
@@ -502,6 +543,24 @@ export class FileJsDb {
         this.refresh();
         return [...this.state.events];
     }
+    /** Read-only projection of the materialized authority state. */
+    authorityStateSummary() {
+        this.refresh();
+        const cardinalities = new Map();
+        for (const key of Object.keys(this.state.rows)) {
+            const separator = key.indexOf(':');
+            const collection = separator === -1 ? key : key.slice(0, separator);
+            cardinalities.set(collection, (cardinalities.get(collection) ?? 0) + 1);
+        }
+        return {
+            current_sequence: this.state.sequence,
+            records: Object.keys(this.state.rows).length,
+            events: this.state.events.length,
+            collections: [...cardinalities]
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([collection, records]) => ({ collection, records })),
+        };
+    }
     export_operations(sinceSequence) {
         this.refresh();
         return this.state.events.filter(event => event.sequence > sinceSequence);
@@ -812,7 +871,8 @@ export class FileJsDb {
             return {
                 updated: true,
                 currentVersion: params.expectedVersion + 1,
-                currentEpoch
+                currentEpoch,
+                item: newValue
             };
         }
         catch (error) {

package/dist/http-db.d.ts

@@ -175,6 +175,8 @@ export declare class HttpJsDb implements JsDb {
         operations: number;
         stateBefore: number;
         stateAfter: number;
+        revisionId: string;
+        operationIds: string[];
     }>;
     /**
      * Atomically create a record only if the key is free.
@@ -244,6 +246,8 @@ export declare class HttpJsDb implements JsDb {
     acquireContent(hash: string): Promise<Uint8Array | null>;
     command(path: string, body: unknown): Promise<any>;
     application_request<T>(path: string, init?: RequestInit): Promise<T>;
+    /** Canonical HTTP adapter used by the typed public substrate contract. */
+    public_request<T>(path: string, init?: RequestInit): Promise<T>;
     /**
      * Subscribe to change notifications.
      *

package/dist/http-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-db.d.ts","sourceRoot":"","sources":["../src/http-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAEkD,KAAK,mBAAmB,EAChF,MAAM,uBAAuB,CAAC;AAE/B,UAAU,QAAQ;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,kBAAkB;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,CAAC;IACpF;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAGD,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACxH,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7D,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,0BAA0B,CAAC,EAAE,MAAM,CAAC;QACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAiBD,iFAAiF;AACjF,qBAAa,QAAS,YAAW,IAAI;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IAErD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IAEjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,SAAS,CAAC,CAAiB;IACnC,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,iBAAiB,CAAK;gBAElB,OAAO,EAAE,kBAAkB;IAUvC;;;;;;;OAOG;IACH,MAAM,IAAI,mBAAmB;IA2B7B,2EAA2E;IAC3E,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,iBAAiB;IAUnB,YAAY,CAAC,CAAC,SAAS;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,SAAS,EAAE,QAAQ,GAAC,QAAQ,GAAC,SAAS,GAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAarI,OAAO,CAAC,QAAQ;IAQhB;;;;;;;;;;;;;;;OAeG;YACW,UAAU;IAgBxB,+EAA+E;IAC/E,aAAa,IAAI,mBAAmB,CAAC,gBAAgB,CAAC;YAIxC,SAAS;IAMvB,OAAO,CAAC,mBAAmB;YAKb,oBAAoB;IAK5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmBnC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAyB5C,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IA4B1G,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoBrD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmB3D;;;;;OAKG;IACG,kBAAkB,CAAC,OAAO,EAAE;QAChC,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,KAAK,CAAC;YAChB,UAAU,EAAE,MAAM,CAAC;YACnB,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,aAAa,CAAC,EAAE,OAAO,CAAC;YACxB,eAAe,CAAC,EAAE,MAAM,CAAC;YACzB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,eAAe,CAAC,EAAE,MAAM,CAAC;SAC1B,CAAC,CAAC;QACH,aAAa,CAAC,EAAE,KAAK,CAAC;YACpB,UAAU,EAAE,MAAM,CAAC;YACnB,EAAE,EAAE,MAAM,CAAC;YACX,aAAa,CAAC,EAAE,OAAO,CAAC;YACxB,eAAe,CAAC,EAAE,MAAM,CAAC;YACzB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,eAAe,CAAC,EAAE,MAAM,CAAC;SAC1B,CAAC,CAAC;KACJ,GAAG,OAAO,CAAC;QACV,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,WAAW,CAAC;QACpB,SAAS,EAAE,OAAO,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IAmEF;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IA8B5F;;;;;;;OAOG;YACW,UAAU;IAqCxB;;;;;;;OAOG;YACW,gBAAgB;IAqBxB,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IA+CnQ,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiB5C,mEAAmE;IAC7D,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAOtE,qEAAqE;IAC/D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAQzE,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAMxD,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAMxF,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAOxD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAQlD,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAgC9E;;;;;;;;OAQG;IACH,iBAAiB,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;YAavD,aAAa;YAsFb,OAAO;IASrB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC7D,UAAU,IAAI,QAAQ;IACtB,SAAS,IAAI,QAAQ;IACrB,QAAQ,IAAI,QAAQ;IACpB,aAAa,IAAI,QAAQ;IACzB,gBAAgB,IAAI,QAAQ;IAC5B,oBAAoB,IAAI,QAAQ;IAChC,2BAA2B,IAAI,QAAQ;IACvC,WAAW,IAAI,MAAM;IAErB;;;;;;;;OAQG;IACH,YAAY,IAAI,MAAM;IAEtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe,CAAC,CAAS;IAE3B,SAAS,IAAI,OAAO,CAAC,mBAAmB,CAAC;IA0BzC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;YAKrB,IAAI;IAOlB,OAAO,CAAC,MAAM;CAIf"}
+{"version":3,"file":"http-db.d.ts","sourceRoot":"","sources":["../src/http-db.ts"],"names":[],"mappings":"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"}

package/dist/http-db.js

@@ -1,4 +1,4 @@
-import { FeltDBServiceError } from './error-codes.js';
+import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
 import { conditionalRefusal } from './transaction.js';
 import { BoundedBackoff, SingleFlightValue, cancellableDelay, describeFailure, } from './managed-recovery.js';
 /**
@@ -15,6 +15,20 @@ function conditionalTransactionId(purpose) {
         : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
     return `${purpose}-${unique}`;
 }
+/**
+ * The canonical state API exposes storage projection metadata as `_id` and
+ * `_version`. The collection SDK has its own document contract (`id` and
+ * `__version`), so those projection-only fields must not leak into remote
+ * collection values or make managed results differ from embedded results.
+ */
+function managedCollectionRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const record = { ...value };
+    delete record._id;
+    delete record._version;
+    return record;
+}
 /** Network adapter implementing the same collection runtime contract as WASM. */
 export class HttpJsDb {
     url;
@@ -204,7 +218,7 @@ export class HttpJsDb {
             const [collection, id] = this.splitKey(key);
             if (this.applicationId) {
                 const result = await this.canonical('/query', { query: { collection, filter: { operator: 'eq', field: 'id', value: id }, limit: 1 } });
-                return { success: true, data: result.records.length ? JSON.stringify(result.records[0]) : undefined };
+                return { success: true, data: result.records.length ? JSON.stringify(managedCollectionRecord(result.records[0])) : undefined };
             }
             const response = await fetch(`${this.url}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, {
                 headers: this.headers(),
@@ -229,7 +243,7 @@ export class HttpJsDb {
                     const page = await this.canonical('/query', {
                         query: { collection, limit: 100, ...(cursor ? { cursor } : {}) },
                     });
-                    records.push(...page.records);
+                    records.push(...page.records.map(managedCollectionRecord));
                     cursor = page.next_cursor;
                 } while (cursor);
                 return { success: true, data: JSON.stringify(records) };
@@ -259,7 +273,7 @@ export class HttpJsDb {
                     order_by: query.orderBy?.map(value => ({ field: value.field, direction: value.direction })),
                     limit: query.limit, cursor: query.cursor,
                 } });
-            return { records: result.records, nextCursor: result.next_cursor, exhausted: !result.next_cursor, plan: result.plan };
+            return { records: result.records.map(managedCollectionRecord), nextCursor: result.next_cursor, exhausted: !result.next_cursor, plan: result.plan };
         }
         const response = await fetch(`${this.url}/query`, {
             method: 'POST', headers: this.headers(true), body: JSON.stringify(query),
@@ -324,7 +338,11 @@ export class HttpJsDb {
         if (this.applicationId) {
             const operations = request.operations.map(operation => ({
                 kind: operation.value === undefined ? 'delete' : operation.requireAbsent ? 'insert' : 'update',
-                collection: operation.collection, id: operation.id, value: operation.value,
+                collection: operation.collection,
+                id: operation.id,
+                value: operation.value && typeof operation.value === 'object' && !Array.isArray(operation.value)
+                    ? { ...operation.value, id: operation.id }
+                    : operation.value,
             }));
             // Every record-level guard travels as a `record` precondition, which the
             // authority evaluates inside the same lock as the writes and against the
@@ -348,13 +366,21 @@ export class HttpJsDb {
                 expected_lease_id: guard.expectedLeaseId,
             }));
             const result = await this.canonicalTransaction(operations, request.transactionId, guards);
-            return { transactionId: result.transaction_id, baseRevision: result.base_revision, commitRevision: result.commit_revision, status: result.status, duplicate: result.duplicate, operations: operations.length, stateBefore: result.state_before, stateAfter: result.state_after };
+            return { transactionId: result.transaction_id, baseRevision: result.base_revision, commitRevision: result.commit_revision, revisionId: result.revision_id, operationIds: result.operation_ids, status: result.status, duplicate: result.duplicate, operations: operations.length, stateBefore: result.state_before, stateAfter: result.state_after };
+        }
+        let response;
+        try {
+            response = await fetch(`${this.url}/transactions`, {
+                method: 'POST',
+                headers: this.headers(true),
+                body: JSON.stringify(request),
+                signal: AbortSignal.timeout(this.requestTimeoutMs),
+            });
+        }
+        catch (error) {
+            this.recordFailure(error);
+            throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN);
         }
-        const response = await fetch(`${this.url}/transactions`, {
-            method: 'POST',
-            headers: this.headers(true),
-            body: JSON.stringify(request),
-        });
         if (!response.ok) {
             // The authority answers a refused transaction with a structured
             // document. Flattening it to a message here is what would force a
@@ -618,7 +644,8 @@ export class HttpJsDb {
         }
         catch (error) {
             this.recordFailure(error);
-            throw error;
+            const mutating = !['GET', 'HEAD', 'OPTIONS'].includes((init.method ?? 'GET').toUpperCase());
+            throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), mutating ? FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN : FeltDBErrorCode.SERVICE_UNAVAILABLE);
         }
         const text = await response.text();
         let body;
@@ -636,6 +663,40 @@ export class HttpJsDb {
         this.recordSuccess();
         return body;
     }
+    /** Canonical HTTP adapter used by the typed public substrate contract. */
+    async public_request(path, init = {}) {
+        let response;
+        try {
+            response = await fetch(`${this.url}${path}`, {
+                ...init,
+                signal: init.signal ?? AbortSignal.timeout(this.requestTimeoutMs),
+                headers: { ...this.headers(init.body !== undefined), ...(init.headers || {}) },
+            });
+        }
+        catch (error) {
+            this.recordFailure(error);
+            const mutating = !['GET', 'HEAD', 'OPTIONS'].includes((init.method ?? 'GET').toUpperCase());
+            throw new FeltDBServiceError(error instanceof Error ? error.message : String(error), mutating ? FeltDBErrorCode.COMMIT_OUTCOME_UNKNOWN : FeltDBErrorCode.SERVICE_UNAVAILABLE);
+        }
+        const text = await response.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = { message: text };
+        }
+        if (!response.ok) {
+            const error = new FeltDBServiceError(body?.message || body?.error || `FeltDB request failed: HTTP ${response.status}`, body?.code || (response.status === 401 ? FeltDBErrorCode.UNAUTHORIZED
+                : response.status === 403 ? FeltDBErrorCode.FORBIDDEN
+                    : response.status === 404 ? FeltDBErrorCode.NOT_FOUND
+                        : 'INVALID_REQUEST'), body?.request_id, response.status);
+            this.recordFailure(error);
+            throw error;
+        }
+        this.recordSuccess();
+        return body;
+    }
     /**
      * Subscribe to change notifications.
      *

package/dist/index-core.d.ts

@@ -43,6 +43,7 @@ export * from './operation-admission.js';
 export * from './error-codes.js';
 export * from './authority-scope.js';
 export * from './managed-recovery.js';
+export * from './public-contract.js';
 export * from './authorization.js';
 export * from './sync-contract.js';
 export * from './workload.js';

package/dist/index-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index-core.d.ts","sourceRoot":"","sources":["../src/index-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index-core.d.ts","sourceRoot":"","sources":["../src/index-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC9E,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,QAAQ,IAAI,gBAAgB,GAClC,MAAM,eAAe,CAAC;AAEvB;;GAEG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;GAEG;AACH,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC"}

package/dist/index-core.js

@@ -42,6 +42,7 @@ export * from './operation-admission.js';
 export * from './error-codes.js';
 export * from './authority-scope.js';
 export * from './managed-recovery.js';
+export * from './public-contract.js';
 export * from './authorization.js';
 export * from './sync-contract.js';
 export * from './workload.js';

package/dist/memory-db.d.ts

@@ -56,6 +56,7 @@ export declare class MemoryJsDb implements JsDb {
         updated: boolean;
         currentVersion: number;
         currentEpoch?: number;
+        item?: any;
     }>;
     query(capability: string): JsResult;
     get_capability_records(capability: string): JsResult;

package/dist/memory-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-db.d.ts","sourceRoot":"","sources":["../src/memory-db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAA8B,KAAK,mBAAmB,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACrG,OAAO,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAO1F,UAAU,QAAQ;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,aAAa;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;AA6BrK,mEAAmE;AACnE,qBAAa,UAAW,YAAW,IAAI;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,SAAS,EAAE,MAAM;IAW7B,OAAO,CAAC,KAAK;IAOb;;;;;;;;;;OAUG;IACG,kBAAkB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAwB7F,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAU5C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ;IAO5C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAO1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAM7B,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBtF,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAiC1K,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAQnC,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ;IAIpD,UAAU,IAAI,QAAQ;IAItB,SAAS,IAAI,QAAQ;IAIrB,QAAQ,IAAI,QAAQ;IACpB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IACvC,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAC1C,2BAA2B,IAAI,QAAQ;IACvC,oBAAoB,IAAI,QAAQ;IAChC,WAAW,IAAI,MAAM;IACrB,YAAY,IAAI,MAAM;IAEtB;;;;;;;OAOG;IACH,SAAS,IAAI,mBAAmB;IAiB1B,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IAQnC,YAAY;IACZ,iBAAiB,CAAC,aAAa,EAAE,MAAM;IACvC,uBAAuB,CAAC,UAAU,EAAE,aAAa,EAAE;;;;CAmBpD"}
+{"version":3,"file":"memory-db.d.ts","sourceRoot":"","sources":["../src/memory-db.ts"],"names":[],"mappings":"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"}

package/dist/memory-db.js

@@ -137,7 +137,7 @@ export class MemoryJsDb {
         const updated = { ...parsed, __version: newVersion };
         this.rows.set(params.key, updated);
         this.event(params.key.split(':')[0], params.key, 'put', updated);
-        return Promise.resolve({ updated: true, currentVersion: newVersion, currentEpoch });
+        return Promise.resolve({ updated: true, currentVersion: newVersion, currentEpoch, item: updated });
     }
     query(capability) {
         const prefix = `${capability}:`;

package/dist/public-contract.d.ts

@@ -0,0 +1,112 @@
+import type { AuthorityScope } from './authority-scope.js';
+import type { Collection } from './collection.js';
+import type { StateFirstDB } from './db.js';
+import type { AtomicTransactionDocument, AtomicTransactionOptions, AtomicTransactionResult, AtomicTransactionScope } from './transaction.js';
+import type { CreateWorkloadInput, Workload } from './workload.js';
+import type { CausalEvent } from './observe.js';
+export declare const FELTDB_PUBLIC_CONTRACT_VERSION: "1.0";
+declare const cursorBrand: unique symbol;
+/** Opaque resume token. No parsing, comparison, or arithmetic is public. */
+export type FeltDBEventCursor = string & {
+    readonly [cursorBrand]: true;
+};
+export interface PublicTransactionResult extends AtomicTransactionResult {
+    baseRevision: number;
+    commitRevision: number;
+    revisionId: string;
+    operationIds: string[];
+}
+export interface PublicEvent extends CausalEvent {
+    revision_id: string;
+    operation_ids: string[];
+    metadata: CausalEvent['metadata'] & {
+        cursor: FeltDBEventCursor;
+        transaction_id: string;
+        revision_id: string;
+    };
+}
+export interface EventReplayPage {
+    contract_version: typeof FELTDB_PUBLIC_CONTRACT_VERSION;
+    cursor_format: 'fh1';
+    application_id: string;
+    environment: string;
+    events: PublicEvent[];
+    next_cursor: FeltDBEventCursor;
+}
+export interface PublicPrincipal {
+    id: string;
+    tenant_id: string;
+    application_id: string;
+    kind: string;
+    name: string;
+    status: string;
+    capabilities: string[];
+    [key: string]: unknown;
+}
+export interface PublicCapabilityDeclaration {
+    contract: 'feltdb.public.substrate';
+    contract_version: typeof FELTDB_PUBLIC_CONTRACT_VERSION;
+    cursor_format_version: 'fh1';
+    stored_state_schema_version: number;
+    migration_version: string;
+    capabilities: Array<{
+        capability: string;
+        contract_version: string;
+        support: 'supported' | 'unsupported' | 'conditionally_supported';
+        supported_transport: string[];
+        scope_requirements: string;
+        durability_semantics: string;
+        authority_owner: 'canonical_feltdb';
+    }>;
+}
+type PublicRequest = <T>(path: string, init?: RequestInit) => Promise<T>;
+/**
+ * One typed public adapter over the canonical FeltDB authority.
+ *
+ * This class owns no records, versions, cursors, work, provenance, or retry
+ * log. Its fields are routing adapters; destroying this object loses no
+ * durable information.
+ */
+export declare class FeltDBPublicContract {
+    private readonly db;
+    private readonly scope;
+    private readonly applicationId;
+    private readonly environment;
+    private readonly request?;
+    readonly version: "1.0";
+    constructor(db: StateFirstDB, scope: AuthorityScope | undefined, applicationId: string | undefined, environment: string, request?: PublicRequest | undefined);
+    private requireApplicationScope;
+    private authority;
+    readonly state: {
+        collection: <T>(name: string) => Collection<T>;
+        transaction: (build: ((transaction: AtomicTransactionScope) => void | Promise<void>) | AtomicTransactionDocument, options?: AtomicTransactionOptions) => Promise<PublicTransactionResult>;
+    };
+    readonly principals: {
+        list: () => Promise<PublicPrincipal[]>;
+        create: (input: {
+            kind: string;
+            name: string;
+        }) => Promise<PublicPrincipal>;
+        grant: (principalId: string, capability: string) => Promise<PublicPrincipal>;
+    };
+    readonly work: {
+        create: (input: CreateWorkloadInput) => Promise<Workload>;
+        inspect: (workId: string) => Promise<Workload>;
+        history: (workId: string) => Promise<unknown>;
+    };
+    readonly events: {
+        replay: (after?: FeltDBEventCursor, options?: {
+            limit?: number;
+        }) => Promise<EventReplayPage>;
+        subscribe: (after: FeltDBEventCursor | undefined, listener: (event: PublicEvent) => void | Promise<void>, options?: {
+            pollIntervalMs?: number;
+            signal?: AbortSignal;
+        }) => (() => void);
+    };
+    readonly provenance: {
+        record: (collection: string, id: string) => Promise<unknown>;
+    };
+    capabilities(): Promise<PublicCapabilityDeclaration>;
+}
+export {};
+//# sourceMappingURL=public-contract.d.ts.map

package/dist/public-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-contract.d.ts","sourceRoot":"","sources":["../src/public-contract.ts"],"names":[],"mappings":"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"}

package/dist/public-contract.js

@@ -0,0 +1,125 @@
+import { FeltDBErrorCode, FeltDBServiceError } from './error-codes.js';
+export const FELTDB_PUBLIC_CONTRACT_VERSION = '1.0';
+/**
+ * One typed public adapter over the canonical FeltDB authority.
+ *
+ * This class owns no records, versions, cursors, work, provenance, or retry
+ * log. Its fields are routing adapters; destroying this object loses no
+ * durable information.
+ */
+export class FeltDBPublicContract {
+    db;
+    scope;
+    applicationId;
+    environment;
+    request;
+    version = FELTDB_PUBLIC_CONTRACT_VERSION;
+    constructor(db, scope, applicationId, environment, request) {
+        this.db = db;
+        this.scope = scope;
+        this.applicationId = applicationId;
+        this.environment = environment;
+        this.request = request;
+    }
+    requireApplicationScope() {
+        if (this.scope?.kind !== 'tenant' || !this.applicationId) {
+            throw new FeltDBServiceError('The public durable contract requires explicit tenant and application scope', FeltDBErrorCode.AUTHORITY_SCOPE_REQUIRED);
+        }
+        return { tenantId: this.scope.tenantId, applicationId: this.applicationId };
+    }
+    authority() {
+        this.requireApplicationScope();
+        if (!this.request) {
+            throw new FeltDBServiceError('This capability requires a connected FeltDB authority', FeltDBErrorCode.CONTRACT_UNSUPPORTED);
+        }
+        return this.request;
+    }
+    state = {
+        collection: (name) => {
+            this.requireApplicationScope();
+            return this.db.collection(name);
+        },
+        transaction: (build, options = {}) => {
+            this.requireApplicationScope();
+            return this.db.transaction(build, options);
+        },
+    };
+    principals = {
+        list: async () => {
+            const { applicationId } = this.requireApplicationScope();
+            return this.authority()(`/api/applications/${encodeURIComponent(applicationId)}/principals`);
+        },
+        create: async (input) => {
+            const { applicationId } = this.requireApplicationScope();
+            return this.authority()(`/api/applications/${encodeURIComponent(applicationId)}/principals`, { method: 'POST', body: JSON.stringify(input) });
+        },
+        grant: async (principalId, capability) => this.authority()(`/api/principals/${encodeURIComponent(principalId)}/capabilities`, { method: 'POST', body: JSON.stringify({ capability }) }),
+    };
+    work = {
+        create: async (input) => {
+            const { tenantId, applicationId } = this.requireApplicationScope();
+            if (input.tenant_id !== tenantId || input.application_id !== applicationId) {
+                throw new FeltDBServiceError('Durable Work scope does not match the bound public contract', FeltDBErrorCode.SCOPE_VIOLATION);
+            }
+            return this.authority()('/v1/workloads', {
+                method: 'POST',
+                body: JSON.stringify({ ...input, created_at: input.created_at ?? Math.floor(Date.now() / 1000) }),
+            });
+        },
+        inspect: (workId) => this.authority()(`/v1/workloads/${encodeURIComponent(workId)}`),
+        history: (workId) => this.authority()(`/v1/workloads/${encodeURIComponent(workId)}/history`),
+    };
+    events = {
+        replay: async (after, options = {}) => {
+            const { applicationId } = this.requireApplicationScope();
+            const query = new URLSearchParams({
+                application_id: applicationId,
+                environment: this.environment,
+                limit: String(options.limit ?? 100),
+            });
+            if (after)
+                query.set('cursor', after);
+            return this.authority()(`/v1/public/events/replay?${query}`);
+        },
+        subscribe: (after, listener, options = {}) => {
+            const controller = new AbortController();
+            const cancel = () => controller.abort();
+            options.signal?.addEventListener('abort', cancel, { once: true });
+            void (async () => {
+                let cursor = after;
+                while (!controller.signal.aborted) {
+                    const page = await this.events.replay(cursor);
+                    for (const event of page.events)
+                        await listener(event);
+                    cursor = page.next_cursor;
+                    await new Promise(resolve => {
+                        const timer = setTimeout(resolve, options.pollIntervalMs ?? 250);
+                        controller.signal.addEventListener('abort', () => {
+                            clearTimeout(timer);
+                            resolve();
+                        }, { once: true });
+                    });
+                }
+            })().catch(() => {
+                // Delivery failure ends this discardable subscriber. Replay remains
+                // available from the caller's last acknowledged opaque cursor.
+                controller.abort();
+            });
+            return cancel;
+        },
+    };
+    provenance = {
+        record: async (collection, id) => {
+            const { applicationId } = this.requireApplicationScope();
+            const query = new URLSearchParams({
+                application_id: applicationId,
+                environment: this.environment,
+            });
+            return this.authority()(`/v1/control-plane/provenance/${encodeURIComponent(collection)}/${encodeURIComponent(id)}?${query}`);
+        },
+    };
+    async capabilities() {
+        const declaration = await this.authority()('/v1/control-plane/capabilities');
+        return declaration.public_contract;
+    }
+}

package/dist/studio/app.d.ts

@@ -16,6 +16,29 @@ export interface StudioAppProps {
     sourceSync?: SourceSyncConfiguration;
     onConnect?: (url: string, token: string) => void;
 }
+export interface ApplicationConnectionNoticeProps {
+    registration?: {
+        namespace?: string;
+    };
+}
+export type StudioConnectionResolution = {
+    source: 'explicit-authority' | 'configured-authority';
+    authorityUrl: string;
+} | {
+    source: 'injected';
+    authorityUrl: '';
+} | {
+    source: 'browser';
+    authorityUrl: '';
+};
+export declare function resolveStudioConnection(input: {
+    explicitAuthority?: string | null;
+    configuredAuthority?: string | null;
+    injected?: boolean;
+}): StudioConnectionResolution;
+/** A registration proves the application is connected; it does not identify
+ * the JavaScript environment in which the application itself executes. */
+export declare function ApplicationConnectionNotice({ registration }: ApplicationConnectionNoticeProps): React.JSX.Element;
 export declare function StudioApp({ db, remoteUrl, token, namespace, deploymentRuntime, applicationUrl, applicationId, environment, developmentSession, managedPublish, sourceSync, onConnect }: StudioAppProps): React.JSX.Element;
 export default StudioApp;
 //# sourceMappingURL=app.d.ts.map