@aithos/sdk 0.1.0-alpha.26 → 0.1.0-alpha.27

package/dist/src/ethos.d.ts

@@ -71,6 +71,44 @@ export declare class EthosClient {
      * so the next read picks up the fresh edition.
      */
     publish(): Promise<PublishResult>;
+    /**
+     * 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.
+     */
+    ensureInitialized(): Promise<{
+        alreadyInitialized: true;
+    } | {
+        alreadyInitialized: false;
+        editionHeight: number;
+        manifestHash: string;
+    }>;
     _readZone(zone: ZoneName): Promise<readonly Section[]>;
     _stageAdd(zone: ZoneName, input: AddSectionInput): void;
     _stageUpdate(zone: ZoneName, sectionId: string, patch: UpdateSectionPatch): void;

package/dist/src/ethos.js

@@ -203,6 +203,98 @@ export class EthosClient {
         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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aithos/sdk",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.27",
   "description": "Aithos SDK \u2014 high-level TypeScript developer kit for building agentic apps on the Aithos protocol. Wraps @aithos/protocol-client and exposes the Aithos compute proxy and wallet (Stripe top-up) endpoints.",
   "keywords": [
     "aithos",