@aithos/sdk 0.1.0-alpha.43 → 0.1.0-alpha.45

package/dist/src/data.js

@@ -38,6 +38,7 @@ import { hkdf } from "@noble/hashes/hkdf.js";
 import { sha256, sha512 } from "@noble/hashes/sha2.js";
 import { XChaCha20Poly1305 } from "@stablelib/xchacha20poly1305";
 import * as ed from "@noble/ed25519";
+import { multibaseToEd25519PublicKey, edPubToX25519Pub, } from "@aithos/protocol-client";
 import { contactsV1 } from "./data-schema-contacts-v1.js";
 import { signOwnerEnvelope } from "./internal/envelope.js";
 // noble/ed25519 v2 needs sha512 wired in for sync sign/verify
@@ -57,15 +58,48 @@ const SCHEMAS = new Map([
 export function createDataClient(args) {
     return new DataClientImpl(args);
 }
-/* -------------------------------------------------------------------------- */
-/*  Implementation                                                            */
-/* -------------------------------------------------------------------------- */
+/**
+ * Build a read-only data client that reads a subject's collections under
+ * a mandate (delegate path). The returned {@link ReadonlyDataClient}
+ * signs every request as the delegate (bare-multibase verificationMethod
+ * + the mandate attached to the envelope), and decrypts records using the
+ * CMK the owner re-wrapped for this delegate via
+ * {@link DataClient.authorizeDelegate}.
+ *
+ * Writes are not available on the returned type and throw `-32042` if
+ * forced.
+ */
+export function createDelegateDataClient(args) {
+    const granteePubMb = args.granteePubkeyMultibase ??
+        args.mandate.grantee?.pubkey;
+    if (!granteePubMb) {
+        throw new Error("createDelegateDataClient: mandate.grantee.pubkey is missing; pass granteePubkeyMultibase explicitly");
+    }
+    return new DataClientImpl({
+        pdsUrl: args.pdsUrl,
+        did: args.subjectDid,
+        // In delegate mode the seed is used only to derive the X25519 key that
+        // unwraps the re-wrapped CMK; envelope signing goes through the
+        // delegate path (buildSignedEnvelope), never signOwnerEnvelope.
+        sphereSeed: args.delegateSeed,
+        verificationMethod: granteePubMb,
+        ...(args.schemas ? { schemas: args.schemas } : {}),
+        ...(args.fetch ? { fetch: args.fetch } : {}),
+        delegate: {
+            delegateSeed: args.delegateSeed,
+            granteePubkeyMultibase: granteePubMb,
+            mandate: args.mandate,
+        },
+    });
+}
 class DataClientImpl {
     #pdsUrl;
     #did;
     #seed;
     #vm;
     #fetch;
+    /** Delegate session, or undefined for the owner path. */
+    #delegate;
     /**
      * Per-client schema overrides, populated from `args.schemas` at
      * construction. Looked up BEFORE the bundled SCHEMAS map (so an app
@@ -82,8 +116,22 @@ class DataClientImpl {
         this.#seed = args.sphereSeed;
         this.#vm = args.verificationMethod;
         this.#fetch = args.fetch ?? globalThis.fetch.bind(globalThis);
+        if (args.delegate)
+            this.#delegate = args.delegate;
         this.#localSchemas = new Map((args.schemas ?? []).map((s) => [s.schema, s]));
     }
+    /** Throw a read-only error when a mutating verb is called on a delegate
+     * client. The PDS rejects these server-side too; this is the fast,
+     * local guard with a precise message. */
+    #assertOwner(op) {
+        if (this.#delegate) {
+            const e = new Error(`sdk.data: "${op}" is not permitted for a delegate client (read-only mandate). ` +
+                `A data.<collection>.read mandate grants get/list only; writes require the owner ` +
+                `or a data.<collection>.write mandate (not yet supported on the delegate path).`);
+            e.code = -32042;
+            throw e;
+        }
+    }
     /**
      * Resolve a schema id to its lite definition. App-supplied schemas
      * (via `createDataClient({ schemas })`) take precedence over the
@@ -95,7 +143,45 @@ class DataClientImpl {
     collection(name) {
         return new DataCollectionImpl(this, name);
     }
+    async authorizeDelegate(args) {
+        this.#assertOwner("authorizeDelegate");
+        const granteePubMb = args.mandate.grantee?.pubkey;
+        if (!granteePubMb) {
+            throw new Error("sdk.data.authorizeDelegate: mandate.grantee.pubkey is required (data read mandates bind to a grantee key).");
+        }
+        // Ensure we hold the collection's CMK (owner unwrap path).
+        const state = await this._ensureCollection(args.collectionName);
+        const cmk = this.#cmkCache.get(args.collectionName);
+        if (!cmk) {
+            throw new Error(`sdk.data.authorizeDelegate: CMK for "${args.collectionName}" not loaded`);
+        }
+        // Derive the grantee's X25519 wrap-recipient key from its Ed25519
+        // public key (the same birational map the owner uses for its own key).
+        const granteeEdPub = multibaseToEd25519PublicKey(granteePubMb);
+        const granteeX25519Pub = edPubToX25519Pub(granteeEdPub);
+        const recipientDidUrl = delegateRecipientDidUrl(granteePubMb);
+        const wrap = this.#wrapCmkForRecipient({
+            cmk,
+            recipientPublicKey: granteeX25519Pub,
+            recipientDidUrl,
+            collectionUrn: state.urn,
+        });
+        await this.#call("/mcp/primitives/write", "aithos.data.authorize_app", {
+            collection_urn: state.urn,
+            mandate: args.mandate,
+            wrap,
+        });
+    }
+    async revokeDelegate(args) {
+        this.#assertOwner("revokeDelegate");
+        await this.#call("/mcp/primitives/write", "aithos.data.revoke_app", {
+            collection_urn: this.#collectionUrn(args.collectionName),
+            mandate_id: args.mandateId,
+            ...(args.reason ? { revocation: { reason: args.reason } } : {}),
+        });
+    }
     async createCollection(args) {
+        this.#assertOwner("createCollection");
         const cmk = randomBytes32();
         const recipientDidUrl = `${this.#did}#data-kex`;
         const collectionUrn = this.#collectionUrn(args.name);
@@ -124,6 +210,20 @@ class DataClientImpl {
             // CMK is retained in cache, only zero the local var if we didn't cache.
         }
     }
+    async ensureCollection(args) {
+        this.#assertOwner("ensureCollection");
+        try {
+            await this.createCollection(args);
+        }
+        catch (e) {
+            // -32073 AITHOS_DATA_COLLECTION_EXISTS → already created (possibly by a
+            // concurrent caller). That's the success case for get-or-create. Any
+            // other error propagates.
+            if (e.code === -32073)
+                return;
+            throw e;
+        }
+    }
     async listCollections() {
         const r = await this.#call("/mcp/primitives/read", "aithos.data.list_collections", {
             subject_did: this.#did,
@@ -146,6 +246,7 @@ class DataClientImpl {
         return this.#call("/mcp/primitives/read", "aithos.data.list_gamma_entries", params);
     }
     async registerSchema(schemaDoc) {
+        this.#assertOwner("registerSchema");
         if (schemaDoc === null || typeof schemaDoc !== "object" || Array.isArray(schemaDoc)) {
             throw new Error("sdk.data.registerSchema: schemaDoc must be a JSON object");
         }
@@ -210,16 +311,27 @@ class DataClientImpl {
             err.code = -32020;
             throw err;
         }
-        // Look up our wrap and unwrap the CMK
-        const ourRecipient = `${this.#did}#data-kex`;
+        // Look up our wrap and unwrap the CMK. Owner: the wrap addressed to
+        // `${did}#data-kex`, unwrapped with the owner sphere seed. Delegate:
+        // the wrap the owner re-wrapped for this grantee
+        // (`did:key:${granteePubkeyMultibase}#data-kex`), unwrapped with the
+        // delegate's own X25519 key (derived from its grantee seed).
+        const ourRecipient = this.#delegate
+            ? delegateRecipientDidUrl(this.#delegate.granteePubkeyMultibase)
+            : `${this.#did}#data-kex`;
         const wrap = meta.cmk_envelope.wraps.find((w) => w.recipient === ourRecipient);
         if (!wrap) {
-            throw new Error(`sdk.data: no CMK wrap for ${ourRecipient} in collection ${name}. The collection was either created with a different recipient, or this client is not the owner.`);
+            throw new Error(this.#delegate
+                ? `sdk.data: no CMK wrap for ${ourRecipient} in collection "${name}". ` +
+                    `The owner has not authorized this delegate on the collection yet — ` +
+                    `ask them to call sdk.data...authorizeDelegate({ collectionName, mandate }).`
+                : `sdk.data: no CMK wrap for ${ourRecipient} in collection ${name}. The collection was either created with a different recipient, or this client is not the owner.`);
         }
+        const unwrapSeed = this.#delegate ? this.#delegate.delegateSeed : this.#seed;
         const cmk = this.#unwrapCmk({
             wrap,
             collectionUrn: meta.urn,
-            privateKey: ed25519SeedToX25519PrivateKey(this.#seed),
+            privateKey: ed25519SeedToX25519PrivateKey(unwrapSeed),
         });
         this.#cmkCache.set(name, cmk);
         const schema = this.#resolveSchema(meta.schema);
@@ -234,6 +346,7 @@ class DataClientImpl {
         return state;
     }
     async _insert(state, record) {
+        this.#assertOwner("insert");
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -288,6 +401,7 @@ class DataClientImpl {
         };
     }
     async _update(state, recordId, record) {
+        this.#assertOwner("update");
         const cmk = this.#cmkCache.get(state.name);
         if (!cmk)
             throw new Error("CMK not loaded");
@@ -306,6 +420,7 @@ class DataClientImpl {
         });
     }
     async _delete(state, recordId) {
+        this.#assertOwner("delete");
         await this.#call("/mcp/primitives/write", "aithos.data.delete_record", {
             collection_urn: state.urn,
             record_id: recordId,
@@ -314,14 +429,31 @@ class DataClientImpl {
     /* -- JSON-RPC dispatch -- */
     async #call(path, method, params) {
         const aud = `${this.#pdsUrl}${path}`;
-        const envelope = await signOwnerEnvelope({
-            iss: this.#did,
-            aud,
-            method,
-            params,
-            verificationMethod: this.#vm,
-            signer: { sign: async (msg) => ed.sign(msg, this.#seed) },
-        });
+        // Both paths use the SAME §11.2 envelope scheme (the data PDS verifies
+        // with @aithos/protocol-core, which canonicalizes the full envelope
+        // INCLUDING `proof` with proofValue=""). Delegate path: sign with the
+        // grantee key, bare-multibase verificationMethod, and attach the mandate
+        // so the PDS resolves the delegation and enforces its scopes.
+        const envelope = this.#delegate
+            ? await signOwnerEnvelope({
+                iss: this.#did, // the SUBJECT DID (mandate issuer), not the delegate
+                aud,
+                method,
+                params,
+                verificationMethod: this.#delegate.granteePubkeyMultibase,
+                signer: {
+                    sign: async (msg) => ed.sign(msg, this.#delegate.delegateSeed),
+                },
+                mandate: this.#delegate.mandate,
+            })
+            : await signOwnerEnvelope({
+                iss: this.#did,
+                aud,
+                method,
+                params,
+                verificationMethod: this.#vm,
+                signer: { sign: async (msg) => ed.sign(msg, this.#seed) },
+            });
         const body = {
             jsonrpc: "2.0",
             id: makeUlid(),
@@ -508,6 +640,18 @@ function cryptoRandom(n) {
 function utf8(s) {
     return new TextEncoder().encode(s);
 }
+/**
+ * Recipient DID URL used for a delegate's CMK wrap. Built from the
+ * grantee's Ed25519 public-key multibase so that (a) the owner side
+ * (`authorizeDelegate`) and the delegate side (`_ensureCollection`)
+ * derive the EXACT same string — it's bound into the wrap AAD and the
+ * HKDF info, so any mismatch fails the unwrap — and (b) the string
+ * contains `mandate.grantee.pubkey`, which the PDS `authorize_app`
+ * handler requires (`wrap.recipient.includes(grantee.pubkey)`).
+ */
+function delegateRecipientDidUrl(granteePubkeyMultibase) {
+    return `did:key:${granteePubkeyMultibase}#data-kex`;
+}
 function aadCmkWrap(collectionUrn, recipient) {
     const p = utf8("aithos-data-cmk-v1\0");
     const c = utf8(collectionUrn);

package/dist/src/index.d.ts

@@ -1,12 +1,14 @@
-export declare const VERSION = "0.1.0-alpha.43";
+export declare const VERSION = "0.1.0-alpha.44";
 export { AithosSDK } from "./sdk.js";
 export type { AithosSDKConfig } from "./types.js";
 export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export type { AithosSdkEndpoints } from "./endpoints.js";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
-export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, } from "./compute.js";
+export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, TranscribeModelId, TranscribeProgressState, TranscribeSegment, TranscribeWord, InvokeTranscribeArgs, InvokeTranscribeResult, PrepareTranscribeArgs, PrepareTranscribeResult, StartTranscribeArgs, StartTranscribeResult, TranscribeStatusResult, TranscribeJobSummary, } from "./compute.js";
 export { ComputeNamespace } from "./compute.js";
+export type { LocalPendingEntry, LocalPendingStatus, TranscribeDraftMeta, TranscribeDraftRecord, } from "./transcribe-resilience.js";
+export { LocalPendingTranscribeTracker, TranscribeDraftStore, TranscribeDraftUnavailableError, } from "./transcribe-resilience.js";
 export type { CreditPackId, CreateTopupSessionArgs, CreateTopupSessionResult, GetBalanceArgs, GetBalanceResult, } from "./wallet.js";
 export { WalletNamespace } from "./wallet.js";
 export type { ComponentStyle, ExtractArgs, ExtractContent, ExtractData, ExtractForm, ExtractFormField, ExtractHeading, ExtractIconDeclaration, ExtractImage, ExtractLink, ExtractLogo, ExtractMeta, ExtractResult, ExtractSection, ExtractStructure, ExtractStyles, FetchAssetArgs, FetchAssetResult, PaletteEntry, VisualSignature, WebNamespaceDeps, } from "./web.js";
@@ -25,6 +27,6 @@ export type { AudienceSet, AppCreditPackId, CreateAppTopupSessionArgs, CreateApp
 export * as onboarding from "./onboarding.js";
 export { createBrowserIdentity, browserIdentityFromStored, type BrowserIdentity, } from "@aithos/protocol-client";
 export type { Section } from "@aithos/protocol-client";
-export { createDataClient, type CreateDataClientArgs, type DataClient, type DataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
+export { createDataClient, createDelegateDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
 export { createAssetsClient, AssetsClient, type CreateAssetsClientArgs, type AttachedContext, type AssetUploadInput, type AssetUploadResult, type AssetFetchResult, type AssetBrief, type ListAssetsOpts, type ThumbnailUploadInput, type ThumbnailUploadResult, type RecipientResolver, type RecipientSet, } from "./assets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -17,7 +17,7 @@
 // Public types specific to the SDK (`AithosSDKConfig`, `AithosSDKError`)
 // are exported from here. Endpoint config (`AithosSdkEndpoints`,
 // `DEFAULT_SDK_ENDPOINTS`) likewise.
-export const VERSION = "0.1.0-alpha.43";
+export const VERSION = "0.1.0-alpha.44";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can
@@ -26,6 +26,7 @@ export { AithosSDKError } from "./types.js";
 export { AithosRpcError } from "@aithos/protocol-client";
 export { DEFAULT_SDK_ENDPOINTS } from "./endpoints.js";
 export { ComputeNamespace } from "./compute.js";
+export { LocalPendingTranscribeTracker, TranscribeDraftStore, TranscribeDraftUnavailableError, } from "./transcribe-resilience.js";
 export { WalletNamespace } from "./wallet.js";
 export { WebNamespace, WEB_EXTRACT_SCOPE } from "./web.js";
 // Sign-up, sign-in, sign-in-with-Google. Lives outside the AithosSDK
@@ -67,7 +68,7 @@ export { createBrowserIdentity, browserIdentityFromStored, } from "@aithos/proto
 // `sdk.data` namespace — Aithos data sub-protocol PDS client. Manages
 // the lifecycle of subject-owned, encrypted, schema-validated records.
 // See spec/data/ in the aithos-protocol repo.
-export { createDataClient, } from "./data.js";
+export { createDataClient, createDelegateDataClient, } from "./data.js";
 // `sdk.assets` — Aithos assets sub-protocol PDS client. Upload,
 // fetch, list, ref/unref binary content (images, PDFs, audio, video)
 // owned by a subject. AEAD-encrypted per-asset under AMKs wrapped for

package/dist/src/internal/envelope.d.ts

@@ -22,6 +22,15 @@ export interface SignedEnvelope {
     readonly exp: number;
     readonly nonce: string;
     readonly params_hash: string;
+    /**
+     * Full signed mandate — present ONLY for a delegate-signed envelope
+     * (§11.6). When present, `proof.verificationMethod` is the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and the
+     * server resolves the signer to that key after verifying the mandate.
+     * The field is part of the signed bytes (the signature commits to the
+     * delegation context), so it cannot be swapped out in transit.
+     */
+    readonly mandate?: unknown;
     readonly proof: {
         readonly type: "Ed25519Signature2020";
         readonly verificationMethod: string;
@@ -54,6 +63,13 @@ export interface SignOwnerEnvelopeArgs {
      * matching public key.
      */
     readonly verificationMethod: string;
+    /**
+     * Full signed mandate, attached to the envelope for a delegate-signed
+     * call (§11.6). When set, `verificationMethod` MUST be the delegate's
+     * bare Ed25519 multibase (matching `mandate.grantee.pubkey`) and
+     * `signer` MUST be the delegate's key. Omit for owner-path envelopes.
+     */
+    readonly mandate?: unknown;
     /** Envelope lifetime in seconds. Default 60. Server caps at 300. */
     readonly ttlSeconds?: number;
     /** Clock override for deterministic tests. Defaults to `new Date()`. */

package/dist/src/internal/envelope.js

@@ -47,6 +47,12 @@ export async function signOwnerEnvelope(args) {
         exp,
         nonce,
         params_hash: paramsHash,
+        // Attach the mandate (delegate path) so the signature commits to the
+        // delegation context. JCS sorts keys, so placement here is irrelevant
+        // to the canonical bytes — what matters is that the server (which
+        // canonicalizes the full envelope incl. mandate + proof/proofValue="")
+        // sees the exact same object.
+        ...(args.mandate !== undefined ? { mandate: args.mandate } : {}),
         proof: {
             type: "Ed25519Signature2020",
             verificationMethod: args.verificationMethod,

package/dist/src/mandates.d.ts

@@ -8,7 +8,28 @@ import type { AithosSdkEndpoints } from "./endpoints.js";
  * directly in `scopes` is rejected at runtime; the compiler can't enforce
  * it (callers who up-cast to string[] would slip through), so the runtime
  * check is the real gate. */
-export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self";
+export type Scope = "ethos.read.public" | "ethos.read.circle" | "ethos.read.self" | "ethos.write.public" | "ethos.write.circle" | "ethos.write.self" | DataScope;
+/** Action a data mandate may authorize on a collection. `write` implies
+ * `read`; `admin` implies `write`. Mirrors the data sub-protocol grammar
+ * `data.<collection>.<action>` (Aithos-protocol `spec/data/04-mandates.md`
+ * §4.2) and the server-side check `requireScope` in data-backend. */
+export type DataAction = "read" | "write" | "admin";
+/**
+ * A data-access scope: `data.<collection>.<action>`, or the cross-collection
+ * wildcard `data.*.<action>`. Examples: `data.contacts.read`,
+ * `data.depots.write`, `data.*.read`.
+ *
+ * Note on `actor_sphere`: data mandates are minted under `actor_sphere:
+ * "self"` (the owner's highest-authority sphere). The sphere is *not* the
+ * access axis for data — the collection is. `actor_sphere` is informative
+ * here; the cryptographic binding is the grantee's key + the CMK wrap, per
+ * spec §4.4. A dedicated `#data` sphere key (independent rotation) MAY be
+ * introduced later without changing this scope grammar.
+ *
+ * Collection names MUST NOT contain `.` (the server splits the scope on
+ * `.` and reads the first three segments).
+ */
+export type DataScope = `data.${string}.${DataAction}`;
 /**
  * The opt-in scope that authorizes a delegate to spend the subject's
  * compute credits via the Aithos compute proxy. Mirror of

package/dist/src/mandates.js

@@ -64,6 +64,17 @@ export class MandatesNamespace {
                 `not by adding "${COMPUTE_INVOKE_SCOPE}" to scopes[]. The namespace forces ` +
                 `an explicit budget and is what a consent UI reviews.`);
         }
+        // Fail fast on malformed data scopes so the misuse surfaces at the SDK
+        // boundary, not as an opaque server rejection at first delegate call.
+        // Accepts `data.<collection>.<action>` and the wildcard `data.*.<action>`.
+        for (const s of input.scopes) {
+            if (s.startsWith("data.") &&
+                !isWellFormedDataScope(s)) {
+                throw new AithosSDKError("mandates_invalid_scopes", `Malformed data scope "${s}". Expected data.<collection>.<action> ` +
+                    `(action = read | write | admin), e.g. "data.contacts.read" or ` +
+                    `"data.*.read". Collection names must not contain ".".`);
+            }
+        }
         // Validate + project the compute namespace if present, then derive
         // the final scopes/constraints to send to the protocol layer.
         const computeProjection = projectCompute(input.compute);
@@ -207,11 +218,41 @@ export class MandatesNamespace {
 /*  Helpers                                                                   */
 /* -------------------------------------------------------------------------- */
 function defaultSphereFromScopes(scopes) {
-    if (scopes.some((s) => s.endsWith(".self")))
+    // Data scopes are sphere-NEUTRAL: they're permitted under self & circle (and
+    // public once the allowlist includes them), and the data access axis is the
+    // collection, not the sphere (the sphere is informative — see {@link DataScope}).
+    // So the actor_sphere of a combined Ethos+data mandate is decided by the
+    // ETHOS scopes alone; data scopes neither raise nor lower it. This makes
+    // `ethos.read.public + data.X.read` default to `public`, `ethos.read.circle
+    // + data.X.read` to `circle`, etc. A caller can always override via
+    // `actorSphere`.
+    const ethos = scopes.filter((s) => !s.startsWith("data."));
+    // Ethos write scopes pin the sphere EXACTLY (a write mandate must be signed
+    // by the sphere it writes to — `validateScopesAgainstSphere`).
+    if (ethos.some((s) => s === "ethos.write.public"))
+        return "public";
+    if (ethos.some((s) => s === "ethos.write.circle"))
+        return "circle";
+    if (ethos.some((s) => s === "ethos.write.self"))
         return "self";
-    if (scopes.some((s) => s.endsWith(".circle")))
+    // Ethos read scopes: narrowest sphere that permits them.
+    if (ethos.some((s) => s.endsWith(".self")))
+        return "self";
+    if (ethos.some((s) => s.endsWith(".circle")))
         return "circle";
-    return "public";
+    // Remaining Ethos scopes (ethos.read.public / .all / gamma.read) → public.
+    if (ethos.length > 0)
+        return "public";
+    // Data-only mandate: sign under `self`. self is the owner's highest-trust
+    // sphere, always permits the scope at mint time (no dependency on the
+    // public-sphere allowlist), and keeps the data grant off the most-exposed
+    // #public key. (Override with `actorSphere` for a public/circle label.)
+    return "self";
+}
+/** `true` iff `s` is a well-formed data scope `data.<collection>.<action>`
+ * with no filter suffix and a non-empty, dot-free collection name. */
+function isWellFormedDataScope(s) {
+    return /^data\.[^.]+\.(read|write|admin)$/.test(s);
 }
 /**
  * Validate the SDK-side `compute` namespace and project it onto the

package/dist/src/react/index.d.ts

@@ -25,4 +25,5 @@
 export { AssetsClientProvider, useAssetsClient, type AssetsClientProviderProps, } from "./context.js";
 export { useAithosAsset, type UseAithosAssetState, type UseAithosAssetOptions, } from "./use-aithos-asset.js";
 export { AithosAsset, type AithosAssetProps, type AithosImageProps, type AithosVideoProps, type AithosAudioProps, type AithosDownloadProps, } from "./AithosAsset.js";
+export { useAithosTranscribePendingJobs, type UseAithosTranscribePendingJobs, } from "./use-transcribe-pending.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/react/index.js

@@ -27,4 +27,5 @@
 export { AssetsClientProvider, useAssetsClient, } from "./context.js";
 export { useAithosAsset, } from "./use-aithos-asset.js";
 export { AithosAsset, } from "./AithosAsset.js";
+export { useAithosTranscribePendingJobs, } from "./use-transcribe-pending.js";
 //# sourceMappingURL=index.js.map

package/dist/src/react/use-transcribe-pending.d.ts

@@ -0,0 +1,21 @@
+import type { ComputeNamespace, InvokeTranscribeResult, TranscribeProgressState } from "../compute.js";
+import type { LocalPendingEntry } from "../transcribe-resilience.js";
+export interface UseAithosTranscribePendingJobs {
+    /** Locally-tracked in-flight jobs (survives reloads via localStorage). */
+    readonly pending: readonly LocalPendingEntry[];
+    /** Resume polling a job by id; resolves with the final transcript. */
+    readonly resume: (jobId: string, opts?: {
+        readonly mandateId?: string;
+        readonly onProgress?: (state: TranscribeProgressState) => void;
+        readonly signal?: AbortSignal;
+        readonly pollIntervalMs?: number;
+    }) => Promise<InvokeTranscribeResult>;
+}
+/**
+ * Subscribe a React component to the SDK's local pending-transcription
+ * registry. Re-renders whenever a job is added, advances, or clears.
+ *
+ * @param compute the SDK compute namespace (`sdk.compute`).
+ */
+export declare function useAithosTranscribePendingJobs(compute: ComputeNamespace): UseAithosTranscribePendingJobs;
+//# sourceMappingURL=use-transcribe-pending.d.ts.map

package/dist/src/react/use-transcribe-pending.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Mathieu Colla
+/**
+ * `useAithosTranscribePendingJobs(sdk.compute)` — a thin React adapter over
+ * the framework-agnostic local pending-jobs tracker exposed by the compute
+ * namespace. The tracker itself (subscribe/getSnapshot) is plain vanilla JS
+ * and works with any framework; this hook just wires it into React's
+ * `useSyncExternalStore`. Vue/Svelte/vanilla users can call
+ * `sdk.compute.subscribeLocalPendingTranscribes` directly.
+ *
+ *     function PendingBanner({ sdk }) {
+ *       const { pending, resume } = useAithosTranscribePendingJobs(sdk.compute);
+ *       if (pending.length === 0) return null;
+ *       return (
+ *         <div>
+ *           {pending.map((p) => (
+ *             <button key={p.jobId} onClick={() => resume(p.jobId)}>
+ *               Resume {p.jobId} ({p.status})
+ *             </button>
+ *           ))}
+ *         </div>
+ *       );
+ *     }
+ */
+import { useCallback, useEffect, useState } from "react";
+/**
+ * Subscribe a React component to the SDK's local pending-transcription
+ * registry. Re-renders whenever a job is added, advances, or clears.
+ *
+ * @param compute the SDK compute namespace (`sdk.compute`).
+ */
+export function useAithosTranscribePendingJobs(compute) {
+    const [pending, setPending] = useState(() => compute.getLocalPendingTranscribesSnapshot());
+    useEffect(() => {
+        // Sync immediately (the snapshot may have changed before mount) then
+        // subscribe. getSnapshot returns a stable reference between mutations,
+        // so identical states bail out of a re-render.
+        setPending(compute.getLocalPendingTranscribesSnapshot());
+        const unsubscribe = compute.subscribeLocalPendingTranscribes(() => {
+            setPending(compute.getLocalPendingTranscribesSnapshot());
+        });
+        return unsubscribe;
+    }, [compute]);
+    const resume = useCallback((jobId, opts) => compute.resumeTranscribe(jobId, opts), [compute]);
+    return { pending, resume };
+}
+//# sourceMappingURL=use-transcribe-pending.js.map

package/dist/src/transcribe-resilience.d.ts

@@ -0,0 +1,57 @@
+export type LocalPendingStatus = "uploading" | "running" | "completed" | "failed";
+export interface LocalPendingEntry {
+    readonly jobId: string;
+    readonly status: LocalPendingStatus;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly meta?: Record<string, unknown>;
+}
+/**
+ * Framework-agnostic observable registry of in-flight transcription jobs.
+ * Persisted to localStorage when available (so it survives reloads), with
+ * an in-memory fallback otherwise. Subscribe with `subscribe(listener)`;
+ * read with `getSnapshot()` (stable reference between mutations, so it
+ * plugs directly into React's `useSyncExternalStore`).
+ */
+export declare class LocalPendingTranscribeTracker {
+    #private;
+    constructor();
+    /** Current entries. Stable reference until the next mutation. */
+    getSnapshot(): readonly LocalPendingEntry[];
+    list(): readonly LocalPendingEntry[];
+    /** Subscribe to changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    upsert(jobId: string, status: LocalPendingStatus, meta?: Record<string, unknown>): void;
+    remove(jobId: string): void;
+    clear(): void;
+}
+export interface TranscribeDraftMeta {
+    readonly title?: string;
+    readonly tag?: string;
+    readonly contentType?: string;
+}
+export interface TranscribeDraftRecord {
+    readonly draftId: string;
+    readonly blob: Blob;
+    readonly metadata: TranscribeDraftMeta;
+    readonly createdAt: number;
+}
+export declare class TranscribeDraftUnavailableError extends Error {
+    constructor();
+}
+/**
+ * IndexedDB-backed queue of recorded audio Blobs. Save a recording the
+ * instant it finishes (before any network), then `upload` it when the
+ * user confirms — so a flaky network or a closed tab never loses audio.
+ * Browser-only: methods reject with {@link TranscribeDraftUnavailableError}
+ * when IndexedDB is absent.
+ */
+export declare class TranscribeDraftStore {
+    save(blob: Blob, meta?: TranscribeDraftMeta): Promise<{
+        readonly draftId: string;
+    }>;
+    list(): Promise<readonly TranscribeDraftRecord[]>;
+    get(draftId: string): Promise<TranscribeDraftRecord | null>;
+    delete(draftId: string): Promise<void>;
+}
+//# sourceMappingURL=transcribe-resilience.d.ts.map