@aithos/sdk 0.1.0-alpha.3 → 0.1.0-alpha.31

package/dist/src/ethos.js

@@ -1,21 +1,826 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright 2026 Mathieu Colla
-// Ethos namespace — re-exports of `@aithos/protocol-client` ethos primitives.
+// `sdk.ethos` namespace — high-level ethos editing.
 //
-// The SDK exposes these so app developers don't need a direct dependency on
-// `@aithos/protocol-client` for the common operations: parsing zone
-// markdown, composing zone documents, building signed editions of the
-// user's ethos.
+// Lazy + commit pattern:
 //
-// The full protocol-client API surface remains available for advanced cases
-// — `import { … } from "@aithos/protocol-client"` is fully supported.
-export { 
-// Zone parser — public-zone markdown → sections.
-parsePublicZone, 
-// Editor — high-level load / mutate / publish flow.
-loadEditSnapshot, publishZoneEdit, publishPublicZoneAsDelegate, publishPrivateZoneAsDelegate, addSectionToList, modifySectionInList, deleteSectionFromList, 
-// Manifest builders — sign editions of the public, circle, or self zones.
-buildSignedFirstEdition, buildSignedNextEdition, 
-// Sphere taxonomy — "public" | "circle" | "self".
-SPHERES, } from "@aithos/protocol-client";
+//   const me = sdk.ethos.me();
+//   me.zone("public").addSection({ title, body });
+//   me.zone("circle").deleteSection(id);
+//   await me.publish();   // 1 edition
+//
+// Mutations stage in memory. `sections()` / `pendingChanges()` /
+// `publish()` are the points where the snapshot is fetched (memoized
+// per zone) and the staged changes are applied on top.
+//
+// Three actor modes:
+//   - owner       — sdk.ethos.me() returns this; full access to public
+//                   + private zones using OwnerSigners
+//   - delegate    — sdk.ethos.of(did) when a mandate matches this
+//                   subject; capability bounded by mandate scopes
+//   - anonymous   — sdk.ethos.of(did) when no mandate matches; public
+//                   zone read-only, every write rejected
+//
+// The namespace stays thin: it builds an EthosClient with the right
+// actor and forwards all real work into protocol-client's
+// `loadEditSnapshot` / `publishZoneEdit` / `publishPublicZoneAsDelegate`
+// / `publishPrivateZoneAsDelegate`.
+import { addSectionToList, AithosRpcError, browserIdentityFromStored, buildSignedEnvelope, buildSignedFirstEditionFromSections, deleteSectionFromList, loadEditSnapshot, modifySectionInList, publishPrivateZoneAsDelegate, publishPublicZoneAsDelegate, publishZoneEdit, signedDidDocument, writeEndpoint, } from "@aithos/protocol-client";
+import { delegateKeyPair } from "./internal/protocol-client-bridge.js";
+import { AithosSDKError } from "./types.js";
+export const ZONE_NAMES = ["public", "circle", "self"];
+/* -------------------------------------------------------------------------- */
+/*  EthosClient — per-subject working buffer                                  */
+/* -------------------------------------------------------------------------- */
+export class EthosClient {
+    subjectDid;
+    mode;
+    #actor;
+    #snapshots = new Map();
+    #mutations = [];
+    /**
+     * Set to `true` when the server reports that no edition has been
+     * published yet for this subject (JSON-RPC code -32020 with the message
+     * `not found: edition for <did>`). Toggled lazily on the first read /
+     * publish attempt and cleared again after a successful first-edition
+     * publish so subsequent operations take the regular `publishZoneEdit`
+     * path.
+     */
+    #ethosHasNoEditionYet = false;
+    constructor(actor) {
+        this.#actor = actor;
+        this.subjectDid = actor.subjectDid;
+        this.mode = actor.kind;
+    }
+    /** Return the per-zone proxy. */
+    zone(name) {
+        if (!ZONE_NAMES.includes(name)) {
+            throw new AithosSDKError("ethos_invalid_zone", `unknown zone "${String(name)}"`);
+        }
+        return new EthosZone(this, name);
+    }
+    hasPendingChanges() {
+        return this.#mutations.length > 0;
+    }
+    pendingChanges() {
+        return this.#mutations.slice();
+    }
+    discard() {
+        this.#mutations = [];
+    }
+    /**
+     * Build and publish a new edition with all staged mutations applied.
+     * Throws if there's nothing staged. After a successful publish, the
+     * mutation buffer is cleared and any cached snapshot is invalidated
+     * so the next read picks up the fresh edition.
+     */
+    async publish() {
+        if (this.#actor.kind === "anonymous") {
+            throw new AithosSDKError("ethos_anonymous_cannot_publish", "anonymous reader has no signing capability");
+        }
+        if (this.#mutations.length === 0) {
+            throw new AithosSDKError("ethos_nothing_to_publish", "no staged mutations; call addSection / updateSection / deleteSection first");
+        }
+        // Compute effective sections per zone, but only for zones that
+        // actually have staged mutations. Zones without staged changes
+        // roll forward by reusing protocol-client's existing bytes.
+        const touched = new Set(this.#mutations.map((m) => m.zone));
+        // Owner-side path is the most common: owner can write any zone they
+        // have staged mutations for. Build everything we need then call
+        // publishZoneEdit once.
+        if (this.#actor.kind === "owner") {
+            // First-edition path: no prior edition exists. Detected when the
+            // tolerant snapshot wrapper returned null on a previous read OR
+            // when this is the first network touch and the server responds
+            // with "not found: edition". Skip the snapshot fetch entirely and
+            // build a height=1 manifest from the staged mutations.
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                return this.#publishFirstEditionOwner();
+            }
+            const newPublic = touched.has("public")
+                ? this.#applyMutations("public", snap.publicSections)
+                : undefined;
+            const newCircle = touched.has("circle")
+                ? this.#applyMutations("circle", snap.circleSections ?? [])
+                : undefined;
+            const newSelf = touched.has("self")
+                ? this.#applyMutations("self", snap.selfSections ?? [])
+                : undefined;
+            const identity = this.#actor.signers._unsafeStoredIdentity();
+            try {
+                const result = await publishZoneEdit({
+                    identity,
+                    snapshot: snap,
+                    // protocol-client's publishZoneEdit always wants newPublic; if we
+                    // didn't touch public we re-publish the existing public sections.
+                    newPublicSections: newPublic ?? snap.publicSections,
+                    ...(newCircle ? { newCircleSections: newCircle } : {}),
+                    ...(newSelf ? { newSelfSections: newSelf } : {}),
+                });
+                this.#afterPublish();
+                return projectPublishResult(result.manifest, this.subjectDid, [
+                    ...touched,
+                ]);
+            }
+            finally {
+                // identity holds raw seeds via reference; not our copy to zeroize
+                // (the underlying seeds live in the OwnerSigners' private fields).
+                // Drop our reference to the temporary StoredIdentity object.
+                void identity;
+            }
+        }
+        // Delegate path. Per-zone scope check + per-zone protocol-client
+        // function. For a multi-zone delegate publish we'd need to call
+        // multiple endpoints; we iterate zones, calling the right primitive.
+        if (this.#actor.kind === "delegate") {
+            const actor = this.#actor.actor;
+            const stored = delegateActorToStored(actor);
+            // Validate scopes upfront.
+            for (const zone of touched) {
+                const required = `ethos.write.${zone}`;
+                const scopes = actor.mandate["scopes"] ?? [];
+                if (!Array.isArray(scopes) || !scopes.includes(required)) {
+                    throw new AithosSDKError("ethos_delegate_scope_missing", `delegate mandate does not grant ${required}`, { data: { mandateId: actor.mandateId, scopes } });
+                }
+            }
+            const snap = await this.#ensureSnapshotDelegate();
+            // Public-zone update — use publishPublicZoneAsDelegate.
+            if (touched.has("public")) {
+                const newPublic = this.#applyMutations("public", snap.publicSections);
+                await publishPublicZoneAsDelegate({
+                    delegate: stored,
+                    snapshot: snap,
+                    newPublicSections: newPublic,
+                });
+            }
+            // Private zones — one publishPrivateZoneAsDelegate call each.
+            for (const zone of ["circle", "self"]) {
+                if (!touched.has(zone))
+                    continue;
+                // CRITICAL — refuse to publish a private zone the delegate
+                // can't decrypt. publishPrivateZoneAsDelegate treats
+                // `newSections` as the COMPLETE new content of the zone (the
+                // server can't merge encrypted bytes it can't read), so if we
+                // forwarded `[]` here the new edition would silently wipe
+                // every section the owner had. This data-loss landed in alpha.9
+                // — alpha.10 turns it into a clean error so the caller knows
+                // the mandate isn't usable until the owner has bootstrapped a
+                // wrap for this delegate (a single owner-side publish on the
+                // zone after mint is enough).
+                if (snap.zoneDecryptErrors?.[zone]) {
+                    throw new AithosSDKError("ethos_delegate_cannot_overwrite_unreadable", `delegate cannot publish to "${zone}": the existing edition is not readable for this delegate (${snap.zoneDecryptErrors[zone]}). Ask the owner to publish ${zone} once so this delegate's wrap is included; only then can the delegate write — otherwise the new edition would replace content this delegate cannot see.`, {
+                        data: {
+                            zone,
+                            mandateId: actor.mandateId,
+                            decryptError: snap.zoneDecryptErrors[zone],
+                        },
+                    });
+                }
+                const base = (zone === "circle"
+                    ? snap.circleSections
+                    : snap.selfSections) ?? [];
+                const newSections = this.#applyMutations(zone, base);
+                await publishPrivateZoneAsDelegate({
+                    delegate: stored,
+                    snapshot: snap,
+                    zone,
+                    newSections,
+                });
+            }
+            this.#afterPublish();
+            // We don't have a single "manifest" to project from since each call
+            // returned its own. Use the last touched call's snapshot as the
+            // base for height — fetch fresh on next read anyway.
+            return {
+                editionHeight: snap.manifest.edition.height + 1,
+                manifestHash: "", // not surfaced by protocol-client today on the delegate path
+                subjectDid: this.subjectDid,
+                zonesPublished: [...touched],
+            };
+        }
+        // Unreachable — anonymous case returned earlier.
+        throw new AithosSDKError("ethos_invalid_actor", "unsupported actor for publish()");
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Bootstrap — first-edition init for fresh Ethos                          */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Idempotently ensure the subject's Ethos has at least one published
+     * edition. Required because a **delegate** cannot bootstrap a first
+     * edition (the first edition's manifest is signed with the owner's
+     * public-sphere key, which delegates do not have). Without an initial
+     * owner-published edition, subsequent delegate writes via
+     * {@link publish} fail with `not found: edition for did:…`.
+     *
+     * Semantics:
+     *   - If an edition already exists (owner OR delegate OR anonymous mode),
+     *     this is a NO-OP and returns `{ alreadyInitialized: true }`.
+     *   - If no edition exists AND the actor is the owner, this stages and
+     *     publishes a height=1 edition containing a single sentinel section
+     *     `aithos-init` in the `public` zone, then returns
+     *     `{ alreadyInitialized: false, editionHeight: 1 }`. Any previously
+     *     staged mutations on this client are preserved and NOT auto-flushed.
+     *   - If no edition exists AND the actor is NOT the owner (delegate or
+     *     anonymous), throws `ethos_bootstrap_not_owner` — only the owner
+     *     can sign a first edition.
+     *
+     * Call site: typically the owner's dashboard, right after sign-in and
+     * before any delegate-mode write (e.g. before triggering a backend
+     * worker that holds a mandate). Idempotent ⇒ safe to call on every
+     * mount.
+     *
+     * Implementation note: this routes through {@link #publishFirstEditionOwner}
+     * which the SDK already uses internally when {@link publish} detects a
+     * fresh Ethos with staged owner mutations. ensureInitialized() exposes
+     * the same code path as an explicit primitive, so the caller doesn't
+     * need to stage a mutation just to trigger first-edition logic.
+     */
+    async ensureInitialized() {
+        // Read attempt — tolerant (returns null if no edition exists). Routes
+        // through the right snapshot method based on actor kind so the
+        // detection is correct in every mode.
+        let snap;
+        if (this.#actor.kind === "anonymous") {
+            snap = await this.#tryEnsureSnapshotAnonymous();
+        }
+        else if (this.#actor.kind === "owner") {
+            snap = await this.#tryEnsureSnapshotOwner();
+        }
+        else {
+            snap = await this.#tryEnsureSnapshotDelegate();
+        }
+        if (snap !== null) {
+            return { alreadyInitialized: true };
+        }
+        // Bootstrap path — owner only.
+        if (this.#actor.kind !== "owner") {
+            throw new AithosSDKError("ethos_bootstrap_not_owner", `subject ${this.subjectDid} has no published edition yet, and only the owner can sign a first edition. Have the owner call ensureInitialized() once (typically from their dashboard at sign-in time).`, { data: { subjectDid: this.subjectDid, actorKind: this.#actor.kind } });
+        }
+        // Stage the sentinel init section. We don't disturb any pre-existing
+        // staged mutations — they'll be picked up by the same first-edition
+        // publish that runs underneath.
+        const prevMutations = this.#mutations.slice();
+        this.#mutations.push({
+            kind: "add",
+            zone: "public",
+            section: {
+                id: "sec_" + randomHex(12),
+                title: "aithos-init",
+                body: "Ethos initialized.\n\n" +
+                    "This section is a sentinel created by `EthosClient.ensureInitialized()` " +
+                    "to materialise the subject's first edition. It is safe to delete or " +
+                    "edit later — its only purpose was to satisfy the protocol's " +
+                    "requirement that an edition contain at least one section.",
+                gamma_ref: "gamma_none_" + randomHex(24),
+            },
+        });
+        try {
+            const result = await this.#publishFirstEditionOwner();
+            // Re-stage the caller's prior mutations (if any) so a subsequent
+            // publish() in the same call sequence picks them up. The init
+            // section we added has been consumed by the publish above.
+            this.#mutations = prevMutations;
+            return {
+                alreadyInitialized: false,
+                editionHeight: result.editionHeight,
+                manifestHash: result.manifestHash,
+            };
+        }
+        catch (e) {
+            // On failure, restore the caller's mutations as they were before
+            // we touched the buffer so the client is left in a consistent state.
+            this.#mutations = prevMutations;
+            throw e;
+        }
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  Internal — snapshot management                                          */
+    /* ------------------------------------------------------------------------ */
+    async _readZone(zone) {
+        if (this.#actor.kind === "anonymous") {
+            if (zone !== "public") {
+                throw new AithosSDKError("ethos_anonymous_private_zone", `anonymous reader cannot access the "${zone}" zone`);
+            }
+            const snap = await this.#tryEnsureSnapshotAnonymous();
+            // No edition yet → no base sections; only staged mutations contribute.
+            const base = snap === null ? [] : snap.publicSections;
+            return this.#applyMutations(zone, base);
+        }
+        if (this.#actor.kind === "owner") {
+            const snap = await this.#tryEnsureSnapshotOwner();
+            if (snap === null) {
+                // No edition yet for this owner — base sections are empty in every
+                // zone. Staged mutations apply on top of an empty list.
+                return this.#applyMutations(zone, []);
+            }
+            const base = baseSectionsFromSnapshot(snap, zone);
+            // Surface decryption errors clearly (if reading a private zone we
+            // can't unwrap, the snapshot has it in zoneDecryptErrors).
+            if (zone !== "public" && snap.zoneDecryptErrors?.[zone]) {
+                throw new AithosSDKError("ethos_zone_unreadable", `cannot read ${zone}: ${snap.zoneDecryptErrors[zone]}`);
+            }
+            return this.#applyMutations(zone, base);
+        }
+        // Delegate
+        const snap = await this.#tryEnsureSnapshotDelegate();
+        if (snap === null) {
+            return this.#applyMutations(zone, []);
+        }
+        const base = baseSectionsFromSnapshot(snap, zone);
+        if (zone !== "public" && snap.zoneDecryptErrors?.[zone]) {
+            throw new AithosSDKError("ethos_zone_unreadable", `cannot read ${zone}: ${snap.zoneDecryptErrors[zone]}`);
+        }
+        return this.#applyMutations(zone, base);
+    }
+    _stageAdd(zone, input) {
+        if (this.#actor.kind === "anonymous") {
+            throw new AithosSDKError("ethos_anonymous_write", "anonymous reader cannot stage mutations");
+        }
+        const section = {
+            id: "sec_" + randomHex(12),
+            title: input.title,
+            body: input.body,
+            gamma_ref: "gamma_none_" + randomHex(24),
+            ...(input.tags && input.tags.length > 0 ? { tags: input.tags } : {}),
+        };
+        this.#mutations.push({ kind: "add", zone, section });
+    }
+    _stageUpdate(zone, sectionId, patch) {
+        if (this.#actor.kind === "anonymous") {
+            throw new AithosSDKError("ethos_anonymous_write", "anonymous reader cannot stage mutations");
+        }
+        this.#mutations.push({ kind: "update", zone, sectionId, patch });
+    }
+    _stageDelete(zone, sectionId) {
+        if (this.#actor.kind === "anonymous") {
+            throw new AithosSDKError("ethos_anonymous_write", "anonymous reader cannot stage mutations");
+        }
+        this.#mutations.push({ kind: "delete", zone, sectionId });
+    }
+    /** Apply staged mutations for a zone on top of base sections. */
+    #applyMutations(zone, base) {
+        let acc = base;
+        for (const m of this.#mutations) {
+            if (m.zone !== zone)
+                continue;
+            switch (m.kind) {
+                case "add":
+                    acc = addSectionToList(acc, {
+                        title: m.section.title,
+                        body: m.section.body,
+                        ...(m.section.tags ? { tags: m.section.tags } : {}),
+                    });
+                    break;
+                case "update":
+                    acc = modifySectionInList(acc, {
+                        sectionId: m.sectionId,
+                        ...(m.patch.title !== undefined ? { title: m.patch.title } : {}),
+                        ...(m.patch.body !== undefined ? { body: m.patch.body } : {}),
+                        ...(m.patch.tags !== undefined ? { tags: m.patch.tags } : {}),
+                    });
+                    break;
+                case "delete":
+                    acc = deleteSectionFromList(acc, m.sectionId);
+                    break;
+            }
+        }
+        return acc;
+    }
+    async #ensureSnapshotOwner() {
+        const cached = this.#snapshots.get("public");
+        if (cached)
+            return cached;
+        if (this.#actor.kind !== "owner") {
+            throw new AithosSDKError("ethos_invalid_actor", "expected owner actor");
+        }
+        const identity = this.#actor.signers._unsafeStoredIdentity();
+        const snap = await loadEditSnapshot(this.subjectDid, identity);
+        this.#cacheSnapshotAllZones(snap);
+        return snap;
+    }
+    async #ensureSnapshotDelegate() {
+        const cached = this.#snapshots.get("public");
+        if (cached)
+            return cached;
+        if (this.#actor.kind !== "delegate") {
+            throw new AithosSDKError("ethos_invalid_actor", "expected delegate actor");
+        }
+        const stored = delegateActorToStored(this.#actor.actor);
+        const snap = await loadEditSnapshot(this.subjectDid, undefined, stored);
+        this.#cacheSnapshotAllZones(snap);
+        return snap;
+    }
+    async #ensureSnapshotAnonymous() {
+        const cached = this.#snapshots.get("public");
+        if (cached)
+            return cached;
+        const snap = await loadEditSnapshot(this.subjectDid);
+        this.#cacheSnapshotAllZones(snap);
+        return snap;
+    }
+    /**
+     * Wrap {@link #ensureSnapshotOwner} so the "no edition published yet"
+     * server response (-32020 with message `not found: edition for <did>`)
+     * is converted into `null`. Once converted, {@link #ethosHasNoEditionYet}
+     * is set to short-circuit subsequent reads without re-hitting the network.
+     *
+     * Returns `null` to mean "subject has an identity but no editions yet —
+     * treat all zones as empty". Any other error is re-thrown.
+     */
+    async #tryEnsureSnapshotOwner() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotOwner();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotDelegate() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotDelegate();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    async #tryEnsureSnapshotAnonymous() {
+        if (this.#ethosHasNoEditionYet)
+            return null;
+        try {
+            return await this.#ensureSnapshotAnonymous();
+        }
+        catch (e) {
+            if (isNoEditionYetError(e)) {
+                this.#ethosHasNoEditionYet = true;
+                return null;
+            }
+            throw e;
+        }
+    }
+    #cacheSnapshotAllZones(snap) {
+        for (const z of ZONE_NAMES)
+            this.#snapshots.set(z, snap);
+    }
+    #afterPublish() {
+        this.#mutations = [];
+        this.#snapshots.clear();
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  First-edition publish (owner)                                           */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Publish height=1 for an owner whose Ethos identity exists on
+     * `api.aithos.be` (provisioned by `auth.signUp()` in alpha.6+) but who
+     * has no editions yet. Builds the manifest from the staged ADD
+     * mutations on the public zone and POSTs `aithos.publish_ethos_edition`.
+     *
+     * Limitations of the alpha.7 cut:
+     *   - Public zone only. Staged mutations on circle/self are rejected
+     *     with `ethos_first_edition_public_only` — those zones can be
+     *     populated in subsequent editions via the regular
+     *     `publishZoneEdit` path once the public zone has been seeded.
+     *   - First-edition publishes don't accept update/delete mutations
+     *     (there's nothing to update or delete yet) — those are rejected
+     *     with `ethos_first_edition_invalid_op`.
+     */
+    async #publishFirstEditionOwner() {
+        if (this.#actor.kind !== "owner") {
+            // Defensive — caller already checked this branch.
+            throw new AithosSDKError("ethos_invalid_actor", "expected owner actor");
+        }
+        // Validate the staged operation set. First edition = ADDs on public
+        // zone only.
+        const publicAdds = [];
+        for (const m of this.#mutations) {
+            if (m.kind !== "add") {
+                throw new AithosSDKError("ethos_first_edition_invalid_op", `first edition: cannot ${m.kind} a section before any edition exists; only addSection is supported on a fresh Ethos`, { data: { mutation: m } });
+            }
+            if (m.zone !== "public") {
+                throw new AithosSDKError("ethos_first_edition_public_only", `first edition: only the "public" zone is supported on a fresh Ethos; "${m.zone}" sections can be added after the first publish`, { data: { zone: m.zone } });
+            }
+            publicAdds.push({ section: m.section });
+        }
+        if (publicAdds.length === 0) {
+            // Should never reach here — publish() short-circuits on empty
+            // mutations. Belt-and-braces in case the contract drifts.
+            throw new AithosSDKError("ethos_first_edition_empty", "first edition: stage at least one public-zone section before publishing");
+        }
+        const identity = this.#actor.signers._unsafeStoredIdentity();
+        const browserId = browserIdentityFromStored(identity);
+        const signedDoc = signedDidDocument(browserId);
+        const built = buildSignedFirstEditionFromSections({
+            identity: browserId,
+            signedDidDoc: signedDoc,
+            publicSections: publicAdds.map((a) => a.section),
+        });
+        const url = writeEndpoint();
+        const params = {
+            manifest: built.manifest,
+            zones: {
+                public: { bytes_base64: bytesToBase64Padded(built.publicMarkdownBytes) },
+            },
+        };
+        const envelope = buildSignedEnvelope({
+            iss: browserId.did,
+            aud: url,
+            method: "aithos.publish_ethos_edition",
+            verificationMethod: `${browserId.did}#public`,
+            params,
+            signer: browserId.public,
+        });
+        const body = JSON.stringify({
+            jsonrpc: "2.0",
+            id: "publish_ethos_edition",
+            method: "aithos.publish_ethos_edition",
+            params: { ...params, _envelope: envelope },
+        });
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body,
+            });
+        }
+        catch (e) {
+            throw new AithosSDKError("ethos_publish_network", `publish_ethos_edition (first edition): network error: ${e.message ?? "unknown"}`);
+        }
+        let json;
+        try {
+            json = (await res.json());
+        }
+        catch {
+            throw new AithosSDKError("ethos_publish_invalid_response", `publish_ethos_edition (first edition): server returned non-JSON (HTTP ${res.status})`);
+        }
+        if (json.error) {
+            throw new AithosSDKError("ethos_first_edition_rejected", `publish_ethos_edition (first edition) rejected: ${json.error.message}`, {
+                status: res.status,
+                data: { rpc_code: json.error.code, ...(json.error.data ?? {}) },
+            });
+        }
+        // Success: clear the no-edition flag so subsequent reads/publishes
+        // take the regular next-edition path.
+        this.#ethosHasNoEditionYet = false;
+        this.#afterPublish();
+        return {
+            editionHeight: 1,
+            manifestHash: "", // protocol-client surfaces this on later editions; not on first
+            subjectDid: browserId.did,
+            zonesPublished: ["public"],
+        };
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  EthosZone — per-zone proxy                                                */
+/* -------------------------------------------------------------------------- */
+export class EthosZone {
+    #parent;
+    #name;
+    constructor(parent, name) {
+        this.#parent = parent;
+        this.#name = name;
+    }
+    get name() {
+        return this.#name;
+    }
+    /** Effective sections (persisted + staged mutations applied). */
+    async sections() {
+        return this.#parent._readZone(this.#name);
+    }
+    addSection(input) {
+        this.#parent._stageAdd(this.#name, input);
+    }
+    updateSection(sectionId, patch) {
+        this.#parent._stageUpdate(this.#name, sectionId, patch);
+    }
+    deleteSection(sectionId) {
+        this.#parent._stageDelete(this.#name, sectionId);
+    }
+    /* ------------------------------------------------------------------------ */
+    /*  By-title helpers                                                        */
+    /*                                                                          */
+    /*  The Aithos protocol does not (yet) treat section titles as a queryable  */
+    /*  index — only `section.id` is a normative anchor. These three methods    */
+    /*  are an ergonomic SDK-side affordance for the common LLM-driven case    */
+    /*  "act on the section called X". They resolve titles client-side by      */
+    /*  loading the full zone (`sections()`) and exact-match filtering on      */
+    /*  `Section.title`.                                                       */
+    /*                                                                          */
+    /*  When a future revision of `aithos.get_ethos_zone` (or a new            */
+    /*  `aithos.find_sections` primitive) supports server-side title           */
+    /*  filtering, the implementation behind these three methods can swap to   */
+    /*  the server call without changing the public signatures here. The      */
+    /*  contract — async, exact case-sensitive match, plural semantics — is    */
+    /*  intentionally aligned with what such an API would return.             */
+    /* ------------------------------------------------------------------------ */
+    /**
+     * Return every section in this zone whose `title` is exactly `title`.
+     *
+     * Match is exact and case-sensitive. The result is always an array — it
+     * may be empty (no match), have one element (the typical case), or have
+     * more than one element when the author has happened to publish two
+     * sections with the same title. Section titles are not required by the
+     * protocol to be unique within a zone.
+     *
+     * The order of returned sections is the zone's authored order
+     * (`sections()` ordering, spec §2.5.2).
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     */
+    async findSectionsByTitle(title) {
+        const all = await this.#parent._readZone(this.#name);
+        return all.filter((s) => s.title === title);
+    }
+    /**
+     * Stage an update for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Apply with `client.publish()` like any other staged mutation. The
+     * staged entries are identical to what `updateSection(id, patch)` would
+     * produce, one per matched section, so `pendingChanges()` /
+     * `discard()` behave normally.
+     *
+     * Note: this method does NOT throw when there is no match — it returns
+     * `[]`. That's intentional: callers driven by an LLM frequently want to
+     * upsert (try update, then fall back to add) and shouldn't have to
+     * catch.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @param patch Same patch shape accepted by `updateSection`.
+     * @returns Array of `section.id` strings whose updates were staged.
+     */
+    async updateSectionsByTitle(title, patch) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageUpdate(this.#name, s.id, patch);
+            ids.push(s.id);
+        }
+        return ids;
+    }
+    /**
+     * Stage a delete for **every** section in this zone whose `title`
+     * matches `title` exactly. Returns the list of section IDs that were
+     * staged — empty when nothing matched.
+     *
+     * Same semantics as {@link updateSectionsByTitle}: silent on no-match,
+     * apply with `client.publish()`.
+     *
+     * @param title Section title to look up — exact, case-sensitive.
+     * @returns Array of `section.id` strings whose deletes were staged.
+     */
+    async deleteSectionsByTitle(title) {
+        const matches = await this.findSectionsByTitle(title);
+        const ids = [];
+        for (const s of matches) {
+            this.#parent._stageDelete(this.#name, s.id);
+            ids.push(s.id);
+        }
+        return ids;
+    }
+}
+export class EthosNamespace {
+    #deps;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * EthosClient for the currently signed-in owner. Throws if there is
+     * no owner — callers should check `auth.canSignAsOwner()` first or
+     * surface the error to the user as "please sign in".
+     */
+    me() {
+        const signers = this.#deps.auth._getOwnerSigners();
+        if (!signers || signers.destroyed) {
+            throw new AithosSDKError("ethos_no_owner", "no owner signed in; sign in with email/password, Google, or a recovery file first");
+        }
+        return new EthosClient({
+            kind: "owner",
+            subjectDid: signers.did,
+            signers,
+        });
+    }
+    /**
+     * EthosClient for an arbitrary subject DID. The mode is resolved at
+     * construction time:
+     *   - if `did` matches the currently signed-in owner → owner mode
+     *   - else if a mandate held by `auth` covers this subject → delegate mode
+     *   - else → anonymous read-only mode
+     *
+     * Async signature so future implementations may do an eager manifest
+     * fetch (e.g. to fail fast on unknown DIDs); today resolution is sync
+     * and the actual fetch happens on the first `sections()` / `publish()`
+     * call.
+     */
+    async of(did) {
+        const owner = this.#deps.auth._getOwnerSigners();
+        if (owner && !owner.destroyed && owner.did === did) {
+            return new EthosClient({
+                kind: "owner",
+                subjectDid: did,
+                signers: owner,
+            });
+        }
+        const delegate = this.#deps.auth._findDelegateForSubject(did);
+        if (delegate && !delegate.destroyed) {
+            return new EthosClient({
+                kind: "delegate",
+                subjectDid: did,
+                actor: delegate,
+            });
+        }
+        return new EthosClient({ kind: "anonymous", subjectDid: did });
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+function baseSectionsFromSnapshot(snap, zone) {
+    switch (zone) {
+        case "public":
+            return snap.publicSections;
+        case "circle":
+            return snap.circleSections ?? [];
+        case "self":
+            return snap.selfSections ?? [];
+    }
+}
+function delegateActorToStored(a) {
+    const kp = delegateKeyPair(a);
+    let hex = "";
+    for (let i = 0; i < kp.seed.length; i++) {
+        hex += kp.seed[i].toString(16).padStart(2, "0");
+    }
+    return {
+        version: "0.1.0",
+        subjectDid: a.subjectDid,
+        mandate: a.mandate,
+        mandateId: a.mandateId,
+        granteeId: a.granteeId,
+        granteePubkeyMultibase: a.granteePubkeyMultibase,
+        delegateSeedHex: hex,
+        importedAt: new Date().toISOString(),
+    };
+}
+function projectPublishResult(manifest, subjectDid, zones) {
+    return {
+        editionHeight: manifest.edition.height,
+        manifestHash: manifest.bundle_id ?? "",
+        subjectDid,
+        zonesPublished: zones,
+    };
+}
+/**
+ * Detect the server-side "no edition published yet" response. Matches the
+ * exact error shape emitted by primitives-read's `notFound("edition for
+ * <did>")` helper: JSON-RPC code -32020 + message starting with `not
+ * found: edition for `. Other -32020 cases (e.g. "not found: manifest
+ * <did>@<height>" raised when the index advertises an edition the S3
+ * bucket can't serve) deliberately fall through — they're symptoms, not
+ * the "fresh subject" case we're trying to swallow.
+ */
+function isNoEditionYetError(e) {
+    if (!(e instanceof AithosRpcError))
+        return false;
+    if (e.code !== -32020)
+        return false;
+    return typeof e.message === "string"
+        && e.message.startsWith("not found: edition for ");
+}
+/**
+ * Standard base64 with `=` padding — matches what protocol-client's
+ * publishZoneEdit uses for `zones.<zone>.bytes_base64`. The server is
+ * tolerant of either padded or unpadded variants per the API contract,
+ * but we mirror the existing wire to keep payloads byte-identical for
+ * easy diffing in dev tools.
+ */
+function bytesToBase64Padded(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function randomHex(n) {
+    const bytes = new Uint8Array(Math.ceil(n / 2));
+    crypto.getRandomValues(bytes);
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex.slice(0, n);
+}
 //# sourceMappingURL=ethos.js.map