@enterstellar-ai/cloud 0.1.0

package/LICENSE

@@ -0,0 +1,196 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement to Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Modifications or such Derivative Works, and to permit recipients
+      of the Modifications to such Derivative Works to do so, subject to
+      the terms of the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer such
+      obligations only on Your own behalf and on Your sole responsibility,
+      not on behalf of any other Contributor, and only if You agree to
+      indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor
+      by reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Do not include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. Please also
+      make a list of the licenses used in the work and ask the
+      maintainers for clarification if needed.
+
+   Copyright 2026 LifeOS Frameworks, Inc. (DBA Enterstellar) and A. Yassin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,17 @@
+Enterstellar
+Copyright 2026 LifeOS Frameworks, Inc. (DBA Enterstellar) and A. Yassin
+
+This product is licensed under the Apache License, Version 2.0 (the "License").
+You may not use this product except in compliance with the License.
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+For licensing inquiries, contact: legal@enterstellar.dev
+Homepage: https://enterstellar.dev
+Repository: https://github.com/enterstellar-ai/enterstellar

package/README.md

@@ -0,0 +1,297 @@
+# @enterstellar-ai/cloud
+
+> Enterstellar Cloud SDK — typed, universal client for `api.enterstellar.dev`. 13 methods + SSE streaming. Throw-on-error. Zero framework dependencies.
+
+## Purpose
+
+`@enterstellar-ai/cloud` provides `createEnterstellarCloudClient()` — the client-side SDK for all Enterstellar Cloud API interactions. Every method returns `CloudResult<T>` with `{ data, ipu }` — a universal wrapper that carries the response data and server-authoritative IPU metering in a single, predictable shape. Operational errors (429, 4xx, retries exhausted) throw `CloudError` with structured metadata (`upgradeUrl`, `retryAfterMs`, `requestId`) — callers never receive degraded or partial results.
+
+**Key properties:**
+
+- **SD3:** Throw-on-error — `CloudError` thrown on 429/4xx/5xx. No degraded returns.
+- **SD5:** Blanket retry — 3 attempts with 1s/2s/4s exponential backoff on 5xx and network errors. Same `X-Idempotency-Key` across retries (AM10).
+- **SD6:** Dual forge API — `forge()` returns a `Promise<CloudResult<ComponentContract>>`. `forge.stream()` returns `AsyncGenerator<ForgeFragment>` for real-time SSE streaming.
+- **SD7:** Universal return type — all methods return `CloudResult<T>` with `{ data: T, ipu: CloudIPU | null }`.
+- **SD1:** Anonymous mode — `pk_anon_*` API keys auto-detected. Only `submitSignal()` is available; all other methods throw `ENS-5004`.
+- **SD9:** Single runtime dependency — `eventsource-parser` (2KB, MIT) for SSE parsing.
+- **CL1:** Hybrid metering — `X-IPU-Used` / `X-IPU-Remaining` / `X-IPU-Cost` headers parsed on every response. Local tracker reconciles with server.
+- **TA2:** Consent-gated traces — dual gate: `config.traceConsent` AND `trace.consent.anonymizedAggregation` must both be `true`.
+- **L15:** Zero framework dependencies — works in Node.js, Deno, browsers, and SSR.
+
+---
+
+## Quick Start
+
+```ts
+import { createEnterstellarCloudClient } from '@enterstellar-ai/cloud';
+
+const cloud = createEnterstellarCloudClient({
+  apiKey: process.env['ENTERSTELLAR_API_KEY']!,
+  traceConsent: true,
+  sessionType: 'app',
+});
+
+// Generate via Cloud Forge (10 IPU):
+const { data: contract, ipu } = await cloud.forge({ intent: 'show patient vitals' });
+console.log(`Cost: ${ipu?.cost} IPU, Remaining: ${ipu?.remaining}`);
+
+// Stream via Cloud Forge SSE (10 IPU):
+for await (const fragment of cloud.forge.stream({ intent: 'show patient vitals' })) {
+  if (fragment.type === 'node') console.log('Partial:', fragment.data);
+  if (fragment.type === 'complete') console.log('Done:', fragment.data);
+}
+
+// Search via Cloud Semantic Index (1 IPU):
+const { data: results } = await cloud.search('patient vitals display', 5);
+
+// Route via Intent Router (1 IPU):
+const { data: prediction } = await cloud.route('sha256_intent_hash');
+
+// Submit trace (0 IPU, consent-gated):
+const {
+  data: { accepted },
+} = await cloud.submitTrace(agentTrace);
+
+// Check usage (0 IPU):
+const { data: usage } = await cloud.getUsage();
+console.log(`${usage.used}/${usage.limit} IPU used (${usage.tier})`);
+
+// Shutdown:
+cloud.dispose();
+```
+
+### Anonymous Mode (`pk_anon_*`)
+
+```ts
+const anonCloud = createEnterstellarCloudClient({ apiKey: 'pk_anon_<install_id>' });
+
+// Only submitSignal() is available:
+await anonCloud.submitSignal(signal); // ✅ Works
+
+await anonCloud.forge({ intent: 'x' }); // ❌ Throws ENS-5004
+await anonCloud.search('x'); // ❌ Throws ENS-5004
+```
+
+---
+
+## API Reference
+
+### `createEnterstellarCloudClient(config): EnterstellarCloudClient`
+
+Factory function. Validates config, initializes HTTP + SSE transports with bearer auth, creates IPU tracker, and wires all cloud proxy modules. Auto-detects anonymous mode from `pk_anon_` API key prefix.
+
+**Throws:** `CloudError` `ENS-5001` if `apiKey` is empty, whitespace-only, or missing.
+
+### `EnterstellarCloudClient` Methods
+
+| Method                         | Signature                                                          | IPU | Description                                                                                                                       |
+| :----------------------------- | :----------------------------------------------------------------- | :-: | :-------------------------------------------------------------------------------------------------------------------------------- |
+| `forge(options)`               | `(ForgeOptions) → Promise<CloudResult<ComponentContract>>`         | 10  | Generate a `ComponentContract` via Cloud Forge (SD6).                                                                             |
+| `forge.stream(options)`        | `(ForgeOptions) → AsyncGenerator<ForgeFragment>`                   | 10  | Stream forge via SSE. Yields `meta → node* → property* → complete` (CF6).                                                         |
+| `search(query, topK?)`         | `(string, number?) → Promise<CloudResult<SemanticSearchResult[]>>` |  1  | Search for components via Cloud Semantic Index. Default `topK: 5` (SI5).                                                          |
+| `route(intentHash)`            | `(string) → Promise<CloudResult<RouterPrediction>>`                |  1  | Route an intent hash to predicted components (IR2).                                                                               |
+| `routeBatch(intentHashes)`     | `(string[]) → Promise<CloudResult<RouterPrediction[]>>`            | 1×N | Batch routing. `result.data[i]` corresponds to `intentHashes[i]` (F19).                                                           |
+| `submitSignal(signal)`         | `(ForgeSignal) → Promise<CloudResult<{ accepted }>>`               |  0  | Submit a forge signal. **Only method available in anonymous mode** (SD1, SD4).                                                    |
+| `submitTrace(trace)`           | `(AgentTrace) → Promise<CloudResult<{ accepted }>>`                |  0  | Submit an `AgentTrace`. Consent-gated (TA2): both `config.traceConsent` AND `trace.consent.anonymizedAggregation` must be `true`. |
+| `analytics(query)`             | `(AnalyticsQuery) → Promise<CloudResult<AnalyticsResult>>`         |  5  | Query trace analytics. POST to `/v1/traces/analytics` (F17). 30s timeout.                                                         |
+| `businessAnalytics(query)`     | `(AnalyticsQuery) → Promise<CloudResult<AnalyticsResult>>`         |  5  | Query business analytics. POST to `/v1/analytics/query` (TA10). 30s timeout.                                                      |
+| `getUsage()`                   | `() → Promise<CloudResult<CloudUsage>>`                            |  0  | Query IPU usage for the current billing period.                                                                                   |
+| `getTraces(options?)`          | `(TraceListOptions?) → Promise<CloudResult<TracePage>>`            |  0  | List traces with cursor-based pagination (TA7).                                                                                   |
+| `getLedger(options?)`          | `(LedgerListOptions?) → Promise<CloudResult<LedgerPage>>`          |  0  | List IPU ledger entries with cursor-based pagination (AM13).                                                                      |
+| `certify(contractId)`          | `(string) → Promise<CloudResult<CertifyResult>>`                   | 20  | Start certification. Returns `{ status: 'pending', pollUrl }` (GI5). 90s timeout.                                                 |
+| `deleteProjectData(projectId)` | `(string) → Promise<CloudResult<{ accepted }>>`                    |  0  | GDPR soft-delete. Returns `202 Accepted` (AG9).                                                                                   |
+| `dispose()`                    | `() → void`                                                        |  —  | Release all resources. Post-dispose calls throw `ENS-5002`. Idempotent.                                                           |
+
+### Types
+
+```ts
+/** Configuration for createEnterstellarCloudClient(). */
+type CloudConfig = {
+  readonly apiKey: string; // Bearer token (CL4)
+  readonly baseUrl?: string | undefined; // Default: 'https://api.enterstellar.dev' (SD8)
+  readonly timeoutMs?: number | undefined; // Default: 10_000 (per-operation overrides)
+  readonly traceConsent?: boolean | undefined; // Default: false (TA2)
+  readonly sessionType?: SessionType | undefined; // Default: 'app' (D111)
+};
+
+/** Universal return wrapper for all SDK methods (SD7). */
+type CloudResult<T> = {
+  readonly data: T;
+  readonly ipu: CloudIPU | null; // null in anonymous mode or absent headers
+};
+
+/** IPU metering data from server response headers. */
+type CloudIPU = {
+  readonly used: number; // X-IPU-Used
+  readonly remaining: number; // X-IPU-Remaining
+  readonly cost: number; // X-IPU-Cost
+};
+
+/** 5-variant discriminated union for SSE streaming (CF6). */
+type ForgeFragment =
+  | ForgeMetaFragment // { type: 'meta', data: { provider, model }, ipu }
+  | ForgeNodeFragment // { type: 'node', data: Partial<ComponentContract> }
+  | ForgePropertyFragment // { type: 'property', data: { path, value } }
+  | ForgeCompleteFragment // { type: 'complete', data: ComponentContract, ipu }
+  | ForgeErrorFragment; // { type: 'error', data: { code, message } }
+
+/** Session type for ClickHouse analytics (D111). */
+type SessionType = 'app' | 'browser' | 'os' | 'connect' | 'agent' | 'other';
+```
+
+### Exports
+
+```ts
+// Factory
+export { createEnterstellarCloudClient } from './create-cloud-client.js';
+
+// Error class (for instanceof checks)
+export { CloudError } from './errors.js';
+
+// Constants
+export { CLOUD_SDK_VERSION } from './version.js';
+export { IPU_COSTS } from './metering/ipu-costs.js';
+
+// Types (re-exported for consumer use)
+export type {
+  EnterstellarCloudClient,
+  CloudConfig,
+  CloudIPU,
+  CloudResult,
+  CloudUsage,
+  SessionType,
+  ForgeOptions,
+  ForgeFragment,
+  ForgeFunction,
+  ForgeMetaFragment,
+  ForgeNodeFragment,
+  ForgePropertyFragment,
+  ForgeCompleteFragment,
+  ForgeErrorFragment,
+  RouterPrediction,
+  AnalyticsQuery,
+  AnalyticsResult,
+  TraceListOptions,
+  LedgerListOptions,
+  TracePage,
+  LedgerPage,
+  CertifyResult,
+} from './types.js';
+
+export type { CloudErrorBody } from './errors.js';
+```
+
+---
+
+## Configuration
+
+### `CloudConfig`
+
+| Option         | Type          | Default                          | Description                                                                         |
+| :------------- | :------------ | :------------------------------- | :---------------------------------------------------------------------------------- |
+| `apiKey`       | `string`      | _(required)_                     | Bearer token for `api.enterstellar.dev`. `pk_anon_*` prefix → anonymous mode (SD1). |
+| `baseUrl`      | `string`      | `'https://api.enterstellar.dev'` | Cloud API base URL. Override for staging/self-hosted (SD8).                         |
+| `timeoutMs`    | `number`      | `10_000`                         | Default per-request HTTP timeout. Per-operation overrides apply (F21).              |
+| `traceConsent` | `boolean`     | `false`                          | Client-level trace consent flag (TA2). Must also have per-trace consent.            |
+| `sessionType`  | `SessionType` | `'app'`                          | Session type for ClickHouse analytics (D111).                                       |
+
+### IPU Cost Schedule (§9.1)
+
+| Operation           |  Cost   | API Endpoint                     | Timeout |
+| :------------------ | :-----: | :------------------------------- | :-----: |
+| Cloud Forge         | 10 IPU  | `POST /v1/forge`                 |   30s   |
+| Semantic Search     |  1 IPU  | `POST /v1/semantic-search`       |   10s   |
+| Route               |  1 IPU  | `POST /v1/route`                 |   10s   |
+| Route Batch         | 1×N IPU | `POST /v1/route/batch`           |   10s   |
+| Trace Analytics     |  5 IPU  | `POST /v1/traces/analytics`      |   30s   |
+| Business Analytics  |  5 IPU  | `POST /v1/analytics/query`       |   30s   |
+| Certify             | 20 IPU  | `POST /v1/contracts/:id/certify` |   90s   |
+| Signal Submit       |  0 IPU  | `POST /v1/signals`               |   10s   |
+| Trace Submit        |  0 IPU  | `POST /v1/traces`                |   10s   |
+| Get Traces          |  0 IPU  | `GET /v1/traces`                 |   10s   |
+| Ledger Query        |  0 IPU  | `GET /v1/usage/ledger`           |   10s   |
+| Usage Query         |  0 IPU  | `GET /v1/usage`                  |   10s   |
+| Delete Project Data |  0 IPU  | `DELETE /v1/project/:id/data`    |   10s   |
+
+---
+
+## Error Handling (SD3)
+
+All operational errors throw `CloudError` with structured metadata:
+
+```ts
+try {
+  await cloud.forge({ intent: 'show vitals' });
+} catch (error) {
+  if (error instanceof CloudError) {
+    console.log(error.code); // 'ENS-5003' (base code)
+    console.log(error.cloudCode); // 'ENS-C4290' (server code)
+    console.log(error.upgradeUrl); // 'https://cloud.enterstellar.dev/billing/upgrade'
+    console.log(error.retryAfterMs); // 3600000
+    console.log(error.requestId); // 'req_01HYX...'
+    console.log(error.recoverable); // true (429 is recoverable)
+  }
+}
+```
+
+### Error Codes
+
+| Code        | Module | Recoverable | Description                                                                       |
+| :---------- | :----- | :---------- | :-------------------------------------------------------------------------------- |
+| `ENS-5001`  | cloud  | No          | `apiKey` is empty or missing — configuration error.                               |
+| `ENS-5002`  | cloud  | No          | Method called after `dispose()` — logic error.                                    |
+| `ENS-5003`  | cloud  | Yes         | Server request failed — network/server error, can retry.                          |
+| `ENS-5004`  | cloud  | No          | Method called in anonymous mode — `pk_anon_*` key only supports `submitSignal()`. |
+| `ENS-5005`  | cloud  | Yes         | All 3 retry attempts exhausted — 5xx/network persistent failure.                  |
+| `ENS-C4290` | cloud  | Yes         | IPU quota exceeded — carries `upgradeUrl` and `retryAfterMs`.                     |
+
+### Retry Strategy (SD5)
+
+```
+Transport: fetch POST /v1/{endpoint}
+    │
+    ├── Attempt 1
+    │     5xx/network → wait 1s → Attempt 2
+    │     429         → throw CloudError (ENS-C4290) immediately
+    │     4xx         → throw CloudError immediately (no retry)
+    │     2xx         → parse response → return CloudResult<T>
+    │
+    ├── Attempt 2
+    │     5xx/network → wait 2s → Attempt 3
+    │     Same X-Idempotency-Key as Attempt 1 (AM10)
+    │
+    └── Attempt 3
+          5xx/network → throw CloudError (ENS-5005)
+          2xx         → parse response → return CloudResult<T>
+```
+
+---
+
+## Consent Model (TA2)
+
+Trace submission requires dual consent:
+
+```
+client.submitTrace(trace)
+    │
+    ├── Gate 1: config.traceConsent === true?
+    │     false → return { data: { accepted: false }, ipu: null }  (zero network)
+    │
+    ├── Gate 2: trace.consent.anonymizedAggregation === true?
+    │     false → return { data: { accepted: false }, ipu: null }  (zero network)
+    │
+    └── Both true → POST /v1/traces → return { data: { accepted }, ipu }
+```
+
+---
+
+## Design Choices Applied
+
+SD1 (anonymous mode auto-detection), SD2 (additive semver), SD3 (throw-on-error), SD4 (transparent telemetry), SD5 (blanket retry with backoff), SD6 (dual forge API), SD7 (universal `CloudResult<T>`), SD8 (default `baseUrl`), SD9 (`eventsource-parser` only dep), SD10 (`@enterstellar-cloud/types`), CL1 (hybrid IPU tracking), AM10 (universal idempotency), CF6 (SSE event types), D111 (`sessionType`), TA2 (consent-gated traces), F17 (POST for analytics), F18 (IPU on meta+complete), F19 (batch ordering), F21 (per-operation timeouts), F22 (User-Agent header), L15 (framework-agnostic).
+
+---
+
+## Bible Reference
+
+See [Implementation Bible §9.1–§9.4](../../archive/CLOUD/02-enterstellar-cloud-implementation-bible.md) for the canonical API surface, endpoint mapping, header contract, and error body format.
+See [Locked Design Choices SD1–SD10](../../archive/CLOUD/03-enterstellar-cloud-design-choices.md) for all SDK design decisions.