@aithos/sdk 0.1.0-alpha.53 → 0.1.0-alpha.55

package/README.md

@@ -169,9 +169,11 @@ const { session, passwordMustChange } = await sdk.auth.signInCustodial({
   email: "alice@example.com",
   password: "MyTempPass32chars",
 });
-// Local KeyStore is now hydrated with the 4 Ed25519 sphere seeds —
-// the user can publish ethos editions, mint mandates, invoke compute,
-// exactly as if they had signed in via a recovery file or Google SSO.
+// Local KeyStore is now hydrated with the 5 Ed25519 sphere seeds
+// (root, public, circle, self, #data) — the user can publish ethos
+// editions, mint mandates, invoke compute, and own PDS data/asset
+// collections (signed under the dedicated #data sphere), exactly as if
+// they had signed in via a recovery file or Google SSO.
 if (passwordMustChange) {
   // Optional: nudge the user to set their own password via the
   // standard reset flow.

package/dist/src/assets.d.ts

@@ -39,11 +39,27 @@ export interface CreateAssetsClientArgs {
      * production vanity domain — SEPARATE from the data PDS) when omitted.
      * Override for self-hosting/staging. */
     readonly pdsUrl?: string;
-    /** Subject DID. */
+    /**
+     * Subject DID that owns the assets. The canonical owner is a `did:aithos:…`
+     * account signing under its dedicated `#data` sphere; a `did:key:…` is a
+     * throwaway identity for demos/tests only.
+     */
     readonly did: string;
-    /** Ed25519 sphere seed (32 bytes). */
+    /**
+     * Ed25519 sphere seed (32 bytes) that signs every assets-PDS envelope. For a
+     * `did:aithos` account this MUST be the subject's dedicated **`#data`** sphere
+     * seed (root stays cold). For a `did:key` it is the single embedded key.
+     *
+     * Note: this is the SIGNING key. Per-asset AMKs for private uploads are
+     * wrapped to the attaching context's X25519 key (`#data-kex` / `#circle-kex`
+     * / `#self-kex`) by the RecipientResolver — a separate mechanism.
+     */
     readonly sphereSeed: Uint8Array;
-    /** Verification method URL within the DID document (e.g. `<did>#<multibase>` for did:key). */
+    /**
+     * Verification method URL within the DID document used to sign envelopes.
+     * For a `did:aithos` account this is **`<did>#data`**; for a `did:key` it is
+     * `<did>#<multibase>`.
+     */
     readonly verificationMethod: string;
     /** Optional fetch implementation. Defaults to globalThis.fetch. */
     readonly fetch?: typeof fetch;

package/dist/src/auth.js

@@ -976,33 +976,15 @@ export class AithosAuth {
         }
         // Magic-link sign-in path. Mirror `signInCustodial` to materialise
         // the 4 sphere seeds in the keystore.
-        if (resp.seed.byteLength !== 128) {
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `verifyEmail: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         zeroize(resp.encKey);
         // Bootstrap the Ethos on api.aithos.be (cf. notes in signInCustodial).
         // The magic-link flow is the FIRST time the user actually has
@@ -1106,33 +1088,15 @@ export class AithosAuth {
         });
         // Materialise the 4 sphere seeds + session — same shape as the verifyEmail
         // magic-link path. Kept inline (additive; verifyEmail is left untouched).
-        if (resp.seed.byteLength !== 128) {
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `acceptInvite: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         zeroize(resp.encKey);
         const identity = browserIdentityFromStored({
             handle: stored.handle,
@@ -1212,45 +1176,19 @@ export class AithosAuth {
             throw new AithosSDKError("auth_invalid_input", "signInCustodial: email and password are required");
         }
         const resp = await custodialSignIn({ fetchImpl: this.#fetchImpl, authBaseUrl: this.authBaseUrl }, input);
-        // Split the 128-byte seed bundle into the four sphere seeds. The
-        // backend lays them out in the canonical order
-        // [root || public || circle || self] (cf. seed-wrapper.ts).
-        if (resp.seed.byteLength !== 128) {
-            // Legacy 32-byte rows shouldn't happen in production (we wiped the
-            // single test row before redeploying with the 4-seed bundle), but
-            // we surface a clear error rather than silently corrupting the
-            // identity.
-            zeroize(resp.seed);
-            zeroize(resp.encKey);
-            throw new AithosSDKError("auth_custodial_seed_format", `signInCustodial: expected 128-byte seed bundle, got ${resp.seed.byteLength}`);
-        }
-        const seedRoot = resp.seed.slice(0, 32);
-        const seedPublic = resp.seed.slice(32, 64);
-        const seedCircle = resp.seed.slice(64, 96);
-        const seedSelf = resp.seed.slice(96, 128);
-        // Stored shape uses hex strings; round-trip through bytesToHex
-        // so the keyStore record is identical to what signUp(zk) writes.
+        // Split the custodial seed bundle into the sphere seeds. The backend
+        // lays them out in the canonical order [root || public || circle || self]
+        // (128 bytes), plus the dedicated #data sphere when migrated (160 bytes).
+        // See seed-wrapper.ts / custodialSeedsHex.
         const stored = {
             version: "0.1.0-hex",
             did: resp.did,
             handle: resp.handle,
             displayName: resp.displayName,
-            seedsHex: {
-                root: bytesToHex(seedRoot),
-                public: bytesToHex(seedPublic),
-                circle: bytesToHex(seedCircle),
-                self: bytesToHex(seedSelf),
-            },
+            // Accepts 128 (legacy, no #data) or 160 (with #data); zeroizes resp.seed.
+            seedsHex: custodialSeedsHex(resp.seed),
             savedAt: new Date().toISOString(),
         };
-        // Zeroize the raw bundle + the split copies now that they've been
-        // serialised into the keyStore record (hex strings live in the
-        // record; the original bytes can go).
-        zeroize(resp.seed);
-        zeroize(seedRoot);
-        zeroize(seedPublic);
-        zeroize(seedCircle);
-        zeroize(seedSelf);
         // The enc_key is informational here — the custodial blob is empty
         // at first login. We still don't keep it in memory.
         zeroize(resp.encKey);
@@ -1507,6 +1445,46 @@ function bytesToHex(b) {
         out += b[i].toString(16).padStart(2, "0");
     return out;
 }
+/**
+ * Split a custodial seed bundle into the keystore's hex seeds, zeroizing the
+ * raw bytes (the bundle and every slice) before returning.
+ *
+ * Two bundle shapes are accepted, in canonical sphere order:
+ *   - 128 bytes = root || public || circle || self            (legacy, no #data)
+ *   - 160 bytes = root || public || circle || self || data    (V2.2+, with #data)
+ *
+ * A 160-byte bundle yields a `data` seed so the custodial owner carries the
+ * dedicated `#data` sphere — identical to a self-custody / SSO account. A
+ * 128-byte bundle (an account the backend hasn't migrated yet) yields no
+ * `data`; the backend upgrades it to 160 on the user's next sign-in.
+ */
+function custodialSeedsHex(seed) {
+    const len = seed.byteLength;
+    if (len !== 128 && len !== 160) {
+        zeroize(seed);
+        throw new AithosSDKError("auth_custodial_seed_format", `expected a 128- or 160-byte custodial seed bundle, got ${len}`);
+    }
+    const root = seed.slice(0, 32);
+    const pub = seed.slice(32, 64);
+    const circle = seed.slice(64, 96);
+    const self = seed.slice(96, 128);
+    const data = len === 160 ? seed.slice(128, 160) : undefined;
+    const hex = {
+        root: bytesToHex(root),
+        public: bytesToHex(pub),
+        circle: bytesToHex(circle),
+        self: bytesToHex(self),
+        ...(data ? { data: bytesToHex(data) } : {}),
+    };
+    zeroize(root);
+    zeroize(pub);
+    zeroize(circle);
+    zeroize(self);
+    if (data)
+        zeroize(data);
+    zeroize(seed);
+    return hex;
+}
 /**
  * Project a delegate as it appears in a `BlobPlaintext` (extension-kit
  * `StoredDelegate` shape) onto the SDK's own {@link StoredDelegateKeys}.

package/dist/src/compute.d.ts

@@ -90,6 +90,89 @@ export interface InvokeBedrockResult {
      */
     readonly sponsoredRemainingForUser?: number;
 }
+/** A decrypted ethos section in the working-set. */
+export interface WorkingSetSection {
+    readonly id: string;
+    readonly title: string;
+    readonly body: string;
+}
+/**
+ * Client-decrypted data the agentic loop may read server-side. Built in the
+ * browser (where the keys live) from exactly the zones / collections the
+ * mandate grants — the proxy never holds a standing decryption key
+ * (see PLATFORM-COMPUTE-AGENTIC-MCP.md §4). Use {@link ComputeNamespace}
+ * with a `mcp` reference + this working-set.
+ */
+export interface ComputeWorkingSet {
+    /** Decrypted ethos sections, per zone. Only granted zones appear. */
+    readonly ethos?: {
+        readonly public?: readonly WorkingSetSection[];
+        readonly circle?: readonly WorkingSetSection[];
+        readonly self?: readonly WorkingSetSection[];
+    };
+    /** Decrypted structured data, per collection name. */
+    readonly data?: Record<string, readonly Record<string, unknown>[]>;
+}
+/** A tool invocation the loop performed (trace for UI / debugging). */
+export interface ConverseToolCall {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly turn: number;
+}
+export type ConverseStopReason = "end_turn" | "max_tokens" | "stop_sequence" | "max_iterations" | "budget_exhausted";
+export interface RunConversationArgs {
+    /** Mandate id — optional for owner sessions, required for delegate sessions. */
+    readonly mandateId?: string;
+    /** Claude model id (text or vision). */
+    readonly model: string;
+    /** Initial conversation. The loop's internal tool turns are server-side. */
+    readonly messages: readonly ComputeMessage[];
+    /** Optional system prompt. */
+    readonly system?: string;
+    /**
+     * MCP tools to expose to the model. v1 only supports the Aithos server.
+     * Omit `tools` to expose the full Aithos catalogue; pass a subset to narrow.
+     */
+    readonly mcp?: {
+        readonly server: "aithos";
+        readonly tools?: readonly string[];
+    };
+    /**
+     * Client-decrypted working-set the tools read from. Build it with
+     * {@link ComputeNamespace.buildWorkingSet}. Required for any tool that
+     * touches private (circle/self) or structured data.
+     */
+    readonly workingSet?: ComputeWorkingSet;
+    /** Cap on Bedrock turns. Server clamps to its own hard cap. Default 6. */
+    readonly maxIterations?: number;
+    /** Per-turn output token cap. */
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    /** Idempotency key for the WHOLE conversation (generated if omitted). */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface RunConversationResult {
+    /** Final assistant text. */
+    readonly content: string;
+    readonly stopReason: ConverseStopReason;
+    /** Number of Bedrock turns performed (each was a billed call). */
+    readonly iterations: number;
+    /** Token usage summed over all turns. */
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+    /** Trace of the tool calls the loop made. */
+    readonly toolCalls: readonly ConverseToolCall[];
+    /** Total microcredits debited for the whole conversation. */
+    readonly creditsCharged: number;
+    readonly walletBalance: number;
+    readonly auditId: string;
+    readonly fundedBy?: "sponsored" | "grant" | "purchase";
+    readonly receiptId?: string;
+    readonly sponsoredBy?: string;
+}
 /**
  * Stable cross-provider image model ids supported by the Aithos compute
  * proxy. New models can be added on the server side without an SDK
@@ -399,6 +482,21 @@ export declare class ComputeNamespace {
      *   `mandate_revoked`, `insufficient_credits`, …).
      */
     invokeBedrock(args: InvokeBedrockArgs): Promise<InvokeBedrockResult>;
+    /**
+     * Run an agentic conversation: a multi-turn Bedrock tool-calling loop that
+     * runs server-side in a single POST and is billed once for the cumulative
+     * token usage. Tools come from the Aithos MCP (declared via `mcp`); the
+     * model reads private user data from the client-decrypted `workingSet`.
+     *
+     * The loop, tool dispatch, and billing all happen on the proxy — the SDK
+     * makes ONE signed request and gets the final answer. Same signer paths as
+     * {@link invokeBedrock} (owner direct or delegate-under-mandate).
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
+     */
+    runConversation(args: RunConversationArgs): Promise<RunConversationResult>;
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).

package/dist/src/compute.js

@@ -101,6 +101,53 @@ export class ComputeNamespace {
             signal: args.signal,
         });
     }
+    /**
+     * Run an agentic conversation: a multi-turn Bedrock tool-calling loop that
+     * runs server-side in a single POST and is billed once for the cumulative
+     * token usage. Tools come from the Aithos MCP (declared via `mcp`); the
+     * model reads private user data from the client-decrypted `workingSet`.
+     *
+     * The loop, tool dispatch, and billing all happen on the proxy — the SDK
+     * makes ONE signed request and gets the final answer. Same signer paths as
+     * {@link invokeBedrock} (owner direct or delegate-under-mandate).
+     *
+     * @throws {AithosSDKError} `sdk_no_signer`, `sdk_no_delegate_for_mandate`,
+     *   `network`, `http`, `empty`, or any proxy code (`quota_exceeded`,
+     *   `mandate_revoked`, `insufficient_credits`, …).
+     */
+    async runConversation(args) {
+        const { endpoints, fetch: fetchImpl } = this.#deps;
+        const choice = this.#resolveSigner(args.mandateId);
+        const url = computeInvokeUrl(endpoints);
+        const idempotencyKey = args.idempotencyKey ?? generateIdempotencyKey();
+        const params = {
+            app_did: this.#deps.appDid,
+            mandate_id: this.#resolveMandateIdForWire(args.mandateId, choice),
+            model: args.model,
+            messages: args.messages,
+            idempotency_key: idempotencyKey,
+        };
+        if (args.system !== undefined)
+            params.system = args.system;
+        if (args.mcp !== undefined)
+            params.mcp = args.mcp;
+        if (args.workingSet !== undefined)
+            params.working_set = args.workingSet;
+        if (args.maxTokens !== undefined)
+            params.max_tokens = args.maxTokens;
+        if (args.maxIterations !== undefined)
+            params.max_iterations = args.maxIterations;
+        if (args.temperature !== undefined)
+            params.temperature = args.temperature;
+        return await this.#signAndPost({
+            url,
+            method: "aithos.compute_converse",
+            params,
+            choice,
+            fetchImpl,
+            signal: args.signal,
+        });
+    }
     /**
      * Multimodal Bedrock invoke — image + text → text response.
      * Default model: `claude-sonnet-4-6` (vision-capable, reliable JSON).

package/dist/src/data.d.ts

@@ -13,18 +13,25 @@ export interface CreateDataClientArgs {
      * staging (e.g. a raw `execute-api` URL).
      */
     readonly pdsUrl?: string;
-    /** Subject DID — typically did:key:… in dev, did:aithos:… in prod. */
+    /**
+     * Subject DID that owns the data. The canonical owner is a `did:aithos:…`
+     * account signing under its dedicated `#data` sphere (see below). A
+     * `did:key:…` is a throwaway identity for quick demos/tests only — it has no
+     * sphere separation (every sphere collapses to the single embedded key).
+     */
     readonly did: string;
     /**
-     * Ed25519 sphere seed (32 bytes). For did:key this is the same as
-     * the key embedded in the DID itself. For did:aithos this is the
-     * subject's `#data` (or `#public`) sphere key.
+     * Ed25519 sphere seed (32 bytes) that signs every PDS envelope. For a
+     * `did:aithos` account this MUST be the subject's dedicated **`#data`** sphere
+     * seed — never the root key nor an Ethos sphere — so the root stays cold and
+     * data operations are isolated to their own key. For a `did:key` it is the
+     * single key embedded in the DID.
      */
     readonly sphereSeed: Uint8Array;
     /**
-     * The verification method URL within the DID document used to sign
-     * envelopes. For did:key this is `<did>#<multibase>`. For did:aithos
-     * this is `<did>#data` (or `#public`).
+     * The verification method URL within the DID document used to sign PDS
+     * envelopes. For a `did:aithos` account this is **`<did>#data`**. For a
+     * `did:key` it is `<did>#<multibase>`.
      */
     readonly verificationMethod: string;
     /** Optional fetch implementation. Defaults to globalThis.fetch. */
@@ -339,4 +346,18 @@ export interface CreateAppendDataClientArgs {
  * (insert allowed; get/list/update/delete refused).
  */
 export declare function createAppendDataClient(args: CreateAppendDataClientArgs): AppendOnlyDataClient;
+/**
+ * Derive an {@link AithosSchemaLite} from a PUBLISHED JSON Schema document (the
+ * shape `aithos.data.get_schema` / `registerSchema` round-trip). The field
+ * split is read from the per-property annotations:
+ *   - `aithos:indexable: true` → indexable (server-visible, filter/sort)
+ *   - `aithos:auto: …`         → auto (server-populated, e.g. created_at)
+ *   - anything else            → encrypted (AEAD'd client-side)
+ *
+ * These annotations are authoritative — by convention they mirror the writer's
+ * own lite — so a reader that never bundled the schema can still split records
+ * correctly. `defaults` is left empty (it only matters for inserts; the writer
+ * supplies its own).
+ */
+export declare function liteFromPublishedSchema(doc: object): AithosSchemaLite;
 //# sourceMappingURL=data.d.ts.map

package/dist/src/data.js

@@ -370,8 +370,16 @@ class DataClientImpl {
         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) {
+        // A collection may carry MORE THAN ONE wrap under our recipient label —
+        // e.g. after the #data-sphere dual-read migration an owner collection holds
+        // both the legacy-sphere-sealed wrap (kept so the old app keeps reading) and
+        // a #data-sealed wrap (both labelled `${did}#data-kex`). The label alone
+        // can't tell them apart (it's fixed regardless of the sealing key), so we
+        // try EVERY matching wrap with our key and keep the one that actually
+        // decrypts. For the common single-wrap case this is identical to the old
+        // `find` + unwrap behaviour.
+        const matching = meta.cmk_envelope.wraps.filter((w) => w.recipient === ourRecipient);
+        if (matching.length === 0) {
             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 — ` +
@@ -379,18 +387,46 @@ class DataClientImpl {
                 : `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(unwrapSeed),
-        });
+        const privateKey = ed25519SeedToX25519PrivateKey(unwrapSeed);
+        let cmk;
+        for (const wrap of matching) {
+            try {
+                cmk = this.#unwrapCmk({ wrap, collectionUrn: meta.urn, privateKey });
+                break;
+            }
+            catch {
+                // Wrong wrap for this key (e.g. the legacy-sphere wrap when we hold the
+                // #data key, or vice-versa) — try the next same-label wrap.
+            }
+        }
+        if (!cmk) {
+            throw new Error(`sdk.data: found ${matching.length} CMK wrap(s) for ${ourRecipient} in collection ${name}, ` +
+                `but none could be unwrapped with this client's key. The collection may be sealed to a ` +
+                `different sphere/key than the one this client was constructed with.`);
+        }
         this.#cmkCache.set(name, cmk);
-        const schema = this.#resolveSchema(meta.schema);
+        let schema = this.#resolveSchema(meta.schema);
+        if (!schema) {
+            // Auto-resolve a PUBLISHED vendor schema from the PDS. This lets any
+            // up-to-date client read ANY collection whose owner registered its schema
+            // (via registerSchema) without the reading app having to bundle the lite
+            // locally — the published JSON Schema's `aithos:indexable` / `aithos:auto`
+            // annotations are the authoritative field split (they mirror the writer's
+            // lite by convention). Falls through to the error if nothing is published.
+            try {
+                const published = await this.getSchema(meta.schema, { subjectDid: this.#did });
+                if (published)
+                    schema = liteFromPublishedSchema(published);
+            }
+            catch {
+                // network / not-found — surface the friendly error below
+            }
+        }
         if (!schema) {
-            throw new Error(`sdk.data: schema "${meta.schema}" not known to the SDK. ` +
-                `Pass it via createDataClient({ schemas: [...] }) if it's an ` +
-                `app-defined (vendor) schema, or upgrade the SDK if it's a core ` +
-                `schema added in a later release.`);
+            throw new Error(`sdk.data: schema "${meta.schema}" not known to the SDK and not published ` +
+                `on the PDS for ${this.#did}. Pass it via createDataClient({ schemas: [...] }) ` +
+                `if it's an app-defined (vendor) schema, register it via registerSchema, ` +
+                `or upgrade the SDK if it's a core schema added in a later release.`);
         }
         const state = { name, urn: meta.urn, schema };
         this.#colCache.set(name, state);
@@ -775,6 +811,43 @@ class DataCollectionImpl {
 /* -------------------------------------------------------------------------- */
 /*  Record split (metadata vs payload)                                        */
 /* -------------------------------------------------------------------------- */
+/**
+ * Derive an {@link AithosSchemaLite} from a PUBLISHED JSON Schema document (the
+ * shape `aithos.data.get_schema` / `registerSchema` round-trip). The field
+ * split is read from the per-property annotations:
+ *   - `aithos:indexable: true` → indexable (server-visible, filter/sort)
+ *   - `aithos:auto: …`         → auto (server-populated, e.g. created_at)
+ *   - anything else            → encrypted (AEAD'd client-side)
+ *
+ * These annotations are authoritative — by convention they mirror the writer's
+ * own lite — so a reader that never bundled the schema can still split records
+ * correctly. `defaults` is left empty (it only matters for inserts; the writer
+ * supplies its own).
+ */
+export function liteFromPublishedSchema(doc) {
+    const d = doc;
+    const props = d.properties ?? {};
+    const indexable = new Set();
+    const encrypted = new Set();
+    const auto = new Set();
+    for (const [k, v] of Object.entries(props)) {
+        const hasAuto = v?.["aithos:auto"] !== undefined;
+        const isIndexable = v?.["aithos:indexable"] === true;
+        if (hasAuto)
+            auto.add(k);
+        if (isIndexable)
+            indexable.add(k);
+        if (!isIndexable && !hasAuto)
+            encrypted.add(k);
+    }
+    return {
+        schema: d["aithos:schema"] ?? "",
+        indexable,
+        encrypted,
+        auto,
+        defaults: {},
+    };
+}
 function splitRecord(record, schema) {
     const metadata = {};
     const payload = {};

package/dist/src/index.d.ts

@@ -1,11 +1,11 @@
-export declare const VERSION = "0.1.0-alpha.44";
+export declare const VERSION = "0.1.0-alpha.55";
 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, TranscribeModelId, TranscribeProgressState, TranscribeSegment, TranscribeWord, InvokeTranscribeArgs, InvokeTranscribeResult, PrepareTranscribeArgs, PrepareTranscribeResult, StartTranscribeArgs, StartTranscribeResult, TranscribeStatusResult, TranscribeJobSummary, } from "./compute.js";
+export type { ComputeMessage, ImageAspectRatio, ImageModelId, InvokeBedrockArgs, InvokeBedrockResult, InvokeBedrockVisionArgs, InvokeBedrockVisionResult, InvokeImageArgs, InvokeImageImage, InvokeImageResult, InvokeSegmentationArgs, InvokeSegmentationResult, SegmentPolygon, StopReason, RunConversationArgs, RunConversationResult, ComputeWorkingSet, WorkingSetSection, ConverseToolCall, ConverseStopReason, 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";
@@ -27,6 +27,8 @@ 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, createDelegateDataClient, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, } from "./data.js";
+export { createDataClient, createDelegateDataClient, createAppendDataClient, type CreateDataClientArgs, type CreateDelegateDataClientArgs, type CreateAppendDataClientArgs, type DataClient, type DataCollection, type ReadonlyDataClient, type ReadonlyDataCollection, type AppendOnlyDataClient, type AppendOnlyDataCollection, type ListOpts, type AithosSchemaLite, liteFromPublishedSchema, } from "./data.js";
+export { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, type MigrateOptions, type MigrateProgress, type EnsureDataSphereResult, type RekeyReport, type CollectionRekeyEntry, type CollectionRekeyStatus, type FullMigrationResult, } from "./migrate.js";
+export { buildSignedRotatedDidDocument, rotateEthos, type RotationSeeds, type DidDocumentLike, type RotateEthosOptions, type RotateEthosResult, } from "./rotate.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.44";
+export const VERSION = "0.1.0-alpha.55";
 export { AithosSDK } from "./sdk.js";
 export { AithosSDKError } from "./types.js";
 // Re-export protocol-client's JSON-RPC error type so consumers can
@@ -68,7 +68,20 @@ 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, createDelegateDataClient, createAppendDataClient, } from "./data.js";
+export { createDataClient, createDelegateDataClient, createAppendDataClient, 
+// Derive an AithosSchemaLite from a published JSON Schema (vendor schemas the
+// client didn't bundle). The SDK uses this internally to auto-resolve unknown
+// collection schemas from the PDS; exported for apps that want it directly.
+liteFromPublishedSchema, } from "./data.js";
+// Legacy `#data` sphere migration — add the dedicated #data sphere to a
+// pre-#data identity and re-wrap its collections' CMK from the legacy sphere
+// to #data. Idempotent, owner-only, dry-run capable. See ./migrate.ts.
+export { ensureDataSphere, rekeyLegacyCollections, addDataSphereWrap, migrateLegacyEthosToDataSphere, } from "./migrate.js";
+// Ethos rotation building blocks — buildSignedRotatedDidDocument produces a
+// root-signed, rotated did.json (all spheres + #data, root unchanged) ready for
+// aithos.rotate_sphere_key. The full rotateEthos orchestration (incl. zone
+// recopy) builds on this. See ./rotate.ts.
+export { buildSignedRotatedDidDocument, rotateEthos, } from "./rotate.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/cmk-wrap.d.ts

@@ -0,0 +1,41 @@
+export interface CmkWrap {
+    readonly recipient: string;
+    readonly alg: "x25519-hkdf-sha256-aead";
+    readonly ephemeral_public: string;
+    readonly wrap_nonce: string;
+    readonly wrapped_key: string;
+}
+/** The CMK envelope stored on a collection. */
+export interface CmkEnvelope {
+    readonly alg: string;
+    readonly wraps: CmkWrap[];
+}
+/**
+ * Derive a 32-byte X25519 private key from an Ed25519 seed via SHA-512
+ * truncation + clamping (libsodium crypto_sign_ed25519_sk_to_curve25519).
+ */
+export declare function ed25519SeedToX25519PrivateKey(seed: Uint8Array): Uint8Array;
+export declare function ed25519SeedToX25519PublicKey(seed: Uint8Array): Uint8Array;
+export declare function wrapCmkForRecipient(args: {
+    cmk: Uint8Array;
+    recipientPublicKey: Uint8Array;
+    recipientDidUrl: string;
+    collectionUrn: string;
+}): CmkWrap;
+/**
+ * Try to unwrap the CMK from `wrap` with `privateKey`. Returns the CMK bytes
+ * on success, or `null` when the AEAD tag fails (wrong key / AAD mismatch) —
+ * the migration relies on this null-return to AUTO-DISCOVER which legacy sphere
+ * seed sealed the wrap (try each, the right one verifies).
+ */
+export declare function tryUnwrapCmk(args: {
+    wrap: {
+        recipient: string;
+        ephemeral_public: string;
+        wrap_nonce: string;
+        wrapped_key: string;
+    };
+    collectionUrn: string;
+    privateKey: Uint8Array;
+}): Uint8Array | null;
+//# sourceMappingURL=cmk-wrap.d.ts.map