@consciousclouds/admin-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,171 @@
+                                 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 provided 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 in addition to the NOTICE text from the
+          Work, provided that such additional attribution notices cannot be
+          construed as modifying 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.
+
+   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 conditions of TITLE,
+      MERCHANTIBILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+      responsible for determining the appropriateness of using or
+      redistributing 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 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.
+
+   Copyright 2024 Conscious Clouds
+
+   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/dist/index.d.ts

@@ -0,0 +1,292 @@
+/**
+ * ConsciousClouds Universal Admin SDK — the governance reads behind a Project's AI organization.
+ *
+ * THE ADOPTION CHAIN THIS EXISTS TO CLOSE:
+ *   consumer → this published SDK → Operator Gateway → target-bound Universal projection.
+ *
+ * It is the same seam every product uses; there is no CCU-Admin-only path and no privileged variant. A consumer
+ * that needs a governance read it does not find here extends THIS package for everyone, rather than hand-rolling
+ * a fetch — that is the whole point of the package existing.
+ *
+ * TYPES + THIN HTTP WRAPPERS ONLY. No policy logic lives here. Every authorization decision belongs to the
+ * Operator Gateway and the Control Plane behind it: the SDK never mints identity, never caches a decision, and
+ * never infers one. A caller supplies its own auth headers and the gateway decides.
+ *
+ * WHAT THE TYPES REFUSE TO FLATTEN, because the platform's own truth is not flat:
+ *
+ *   - `enforcement` on every Operative Type. The governed record declares more than the runtime consumes, so a
+ *     type that merged its fields would let a renderer show validated-but-unconsumed configuration as governance
+ *     in force. `enforced` and `declared` are separate lists, and `serving_envelope_source` names which authority
+ *     actually supplies the envelope that bounds a run — the record declares one and the enrollment declaration
+ *     is the one resolved at dispatch. Two truths, both reported.
+ *   - `operation_breadth` as {declared, effective, enforced}. An undeclared ceiling is stored as 0 and fails
+ *     closed to 1, so a single number would read as "no Operatives permitted" — the opposite of the truth.
+ *   - the authority envelope's `scope` and `excluded_terms`. What this reads is the Personality/consent HALF of
+ *     an Operation's authority; the re-proven initiating actor and the immutable Operation bounds are elsewhere.
+ *     A type called "the authority envelope" with seven flat arrays would describe an authority no commission
+ *     actually uses.
+ *   - `evaluated_at` + `evaluation: 'live_uncached_at_read'`. The envelope is a snapshot of a computation, never
+ *     stored state, and the type says so rather than trusting a renderer to remember.
+ */
+export interface AdminClientOptions {
+    /** The Operator Gateway base URL. The SDK never hard-codes it. */
+    baseUrl: string;
+    /** Caller-supplied auth headers (typically Authorization). The SDK never mints identity. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Optional fetch override (tests / non-browser runtimes). */
+    fetch?: typeof fetch;
+}
+/**
+ * A structured non-2xx error carrying the request coordinates and nothing else.
+ *
+ * THE RAW UPSTREAM BODY IS NOT RETAINED — not on `.message`, not on any field. An upstream 500 can carry a stack
+ * trace, a DSN, or a token, and an error object is the single most widely-serialized value in a program: loggers
+ * serialize own properties, crash reporters ship the whole object, `JSON.stringify(err)` is idiomatic. Keeping
+ * the body "for a caller that explicitly needs it" makes every one of those paths a leak.
+ */
+export declare class AdminError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    constructor(method: string, path: string, status: number);
+}
+export interface StorageBindingRead {
+    declared: boolean;
+    status?: string;
+}
+export interface ObserveTopicGrant {
+    project: string;
+    family: string;
+}
+export interface ExecutionEnvelope {
+    cpu: number;
+    memory_mib: number;
+    filesystem_mib: number;
+    output_bytes_max: number;
+    network_egress_allow: string[];
+    timeout_ms: number;
+    lease_ttl_ms: number;
+    teardown_slack_ms: number;
+}
+export interface DelegationGrant {
+    composer_personality: string;
+    target_personality: string;
+    approver?: string;
+    is_execution_grant: boolean;
+    execution_provider?: string;
+    execution_envelope: ExecutionEnvelope | null;
+}
+/**
+ * An Operative declared in a product's enrollment — the AUTHORING half, which is not the same thing as the
+ * governed record's resolution or as what any gate enforces.
+ *
+ * There is deliberately no `preferences` field: it is opaque, product-authored, schema-free JSON, and the
+ * platform-scoped read that feeds this does not serialize it.
+ */
+export interface OperativeDeclaration {
+    id: string;
+    display_name: string;
+    role: string;
+    execution_provider?: string;
+    execution_envelope: ExecutionEnvelope | null;
+    required_capabilities: string[];
+    allowed_commissioners: string[];
+    sandbox_requirement: string;
+    supports_clustering: boolean;
+    escalation: string;
+    description?: string;
+    default_model_policy_ref?: string;
+    max_wall_clock_ms: number;
+    max_iterations: number;
+    artifact_contract: string[];
+}
+/**
+ * The breadth ceiling, told honestly. `declared` is what the product authored (0 = undeclared), `effective` is
+ * what the runtime computes (undeclared fails closed to 1), and `enforced` records that this bound really is
+ * applied — atomically, at the run store's admission boundary.
+ */
+export interface OperationBreadth {
+    declared: number;
+    effective: number;
+    enforced: boolean;
+}
+export interface CapabilityRoute {
+    capability_id: string;
+    route_key: string;
+    endpoint_present: boolean;
+}
+/** A Project's enrollment record: its governed AI configuration, references only — never a secret. */
+export interface EnrollmentDetail {
+    product_id: string;
+    status: string;
+    s2s_trust_mode: string;
+    issuer?: string;
+    jwks_uri?: string;
+    audiences: string[];
+    personality_grants: string[];
+    capability_grants: CapabilityRoute[];
+    knowledge_namespace_grants: string[];
+    cross_project_grants: string[];
+    service_endpoint_keys: string[];
+    storage_bindings: Record<string, StorageBindingRead>;
+    owner?: string;
+    allowed_origins: string[];
+    graph_scope_grants: string[];
+    memory_scope_grants: string[];
+    observe_topic_grants: ObserveTopicGrant[];
+    delegation_grants: DelegationGrant[];
+    operatives: OperativeDeclaration[];
+    /** RETIRED by owner ruling and required to be empty; carried only so a stale record refuses loudly. */
+    operative_roles: string[];
+    /** Capability id → service_endpoints KEY. Never a URL. */
+    capability_routes: Record<string, string>;
+    operation_breadth: OperationBreadth;
+}
+export interface PersonalitySummary {
+    id: string;
+    name?: string;
+    classification?: string;
+    tier?: string;
+    business_package?: string;
+    capabilities?: string[];
+    allowed_tools?: string[];
+    allowed_canvases?: string[];
+}
+/**
+ * A Personality's EFFECTIVE AUTHORITY, computed at read time.
+ *
+ * This is not stored state and the type refuses to imply otherwise. `evaluated_at` is a computation timestamp,
+ * `evaluation` records that the computation is live and uncached, and `scope` + `excluded_terms` say plainly
+ * that this is the Personality/consent half — the re-proven initiating actor and the immutable Operation bounds
+ * are separate terms that a commission applies elsewhere.
+ */
+export interface AuthorityEnvelope {
+    product_id: string;
+    personality_id: string;
+    evaluated_at: string;
+    evaluation: 'live_uncached_at_read';
+    scope: 'personality_consent_half';
+    excluded_terms: string[];
+    mode: string;
+    /** Empty when the envelope resolved; otherwise the reason it refuses, which is an answer, not an error. */
+    refusal: string;
+    dimensions: {
+        capabilities: string[];
+        allowed_tools: string[];
+        allowed_canvases: string[];
+        allowed_adapters: string[];
+        knowledge_namespaces: string[];
+        graph_scopes: string[];
+        memory_scopes: string[];
+    };
+    /** Which dimensions are effective authority ∩ the owning product's enrollment grants; the rest are authority alone. */
+    intersected_with_enrollment: string[];
+}
+/**
+ * Which of a Type's fields actually bind.
+ *
+ * This is data rather than a rendering convention on purpose: a consumer asked to remember which fields are live
+ * will eventually forget, and the failure is silent — an operator reads a bound that does not bind.
+ */
+export interface OperativeTypeEnforcement {
+    /** Fields that reach a gate (census admission, typed commission admission, provider-bound sandbox). */
+    enforced: string[];
+    /** Fields validated at the write boundary, carried in the content digest, and consumed by nothing. */
+    declared: string[];
+    /** Which authority supplies the envelope that actually bounds a run. */
+    serving_envelope_source: string;
+}
+export interface OperativeTypeRecordState {
+    exists: boolean;
+    active_version: number;
+    has_active_version: boolean;
+    lifecycle: string;
+    state_reason?: string;
+    updated_by?: string;
+    updated_at?: string | null;
+}
+export interface OperativeTypeGoverned {
+    resolvable: boolean;
+    refusal_reason?: string;
+    version?: number;
+    role?: string;
+    required_capabilities: string[];
+    allowed_commissioners: string[];
+    sandbox_requirement?: string;
+    supports_clustering: boolean;
+    escalation?: string;
+    execution_provider?: string;
+}
+export interface OperativeTypeView {
+    product_id: string;
+    operative_id: string;
+    record: OperativeTypeRecordState;
+    governed: OperativeTypeGoverned;
+    enforcement: OperativeTypeEnforcement;
+}
+export interface OperativeTypeVersion {
+    version: number;
+    content_digest: string;
+    authored_by: string;
+    authored_at: string;
+    is_active: boolean;
+    role: string;
+    display_name: string;
+}
+export interface OperativeTypeDetail extends OperativeTypeView {
+    history: OperativeTypeVersion[];
+    as_of: string;
+}
+export interface OperativeTypeList {
+    operative_types: OperativeTypeView[];
+    as_of: string;
+}
+/**
+ * AdminClient is a thin wrapper over the Operator Gateway's governance reads. Each method is one request; the
+ * gateway authorizes before proxying, and a non-2xx response throws.
+ *
+ * PRODUCT-OWNED READS CARRY BOTH HALVES OF THEIR IDENTITY on the path. A personality id or an operative id alone
+ * is ambiguous across products, and resolving one by picking a match would show a caller another product's
+ * governance — so the detail methods take (productId, id) and encode both.
+ */
+export declare class AdminClient {
+    private readonly baseUrl;
+    private readonly headersFn;
+    private readonly fetchImpl;
+    constructor(options: AdminClientOptions);
+    private request;
+    /** Every enrolled Project the operator may see. */
+    listEnrollments<T = unknown>(): Promise<T>;
+    /** One Project's enrollment record — its governed AI configuration. */
+    getEnrollment(productId: string): Promise<EnrollmentDetail>;
+    /** The Project portfolio read. */
+    listProjects<T = unknown>(): Promise<T>;
+    /** The personalities the conductor is actually serving (the file registry). */
+    listPersonalities<T = {
+        personalities: PersonalitySummary[];
+    }>(): Promise<T>;
+    /** The governed Personality Records inside the operator's read scope, optionally narrowed to one product. */
+    listPersonalityRecords<T = unknown>(productId?: string): Promise<T>;
+    /** One governed Personality Record and its version history. */
+    getPersonalityRecord<T = unknown>(productId: string, personalityId: string): Promise<T>;
+    /**
+     * A Personality's effective authority, computed live at read time.
+     *
+     * The result is a snapshot of a computation, not stored state, and it covers the Personality/consent half of
+     * an Operation's authority only — the returned object names both facts about itself.
+     */
+    getAuthorityEnvelope(productId: string, personalityId: string): Promise<AuthorityEnvelope>;
+    /**
+     * A product's Operative Type roster.
+     *
+     * `productId` NARROWS within the operator's authorized scope and can never widen it. This is deliberately not
+     * a platform-wide library view: "this product's Operatives" and "every Operative Type known to Universal" are
+     * different reads with different breadth, and only the first is this method.
+     */
+    listOperativeTypes(productId: string): Promise<OperativeTypeList>;
+    /** One Operative Type with its full version history. */
+    getOperativeType(productId: string, operativeId: string): Promise<OperativeTypeDetail>;
+}
+/** Convenience factory, mirroring the other ConsciousClouds SDK clients. */
+export declare function createAdminClient(options: AdminClientOptions): AdminClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,127 @@
+/**
+ * ConsciousClouds Universal Admin SDK — the governance reads behind a Project's AI organization.
+ *
+ * THE ADOPTION CHAIN THIS EXISTS TO CLOSE:
+ *   consumer → this published SDK → Operator Gateway → target-bound Universal projection.
+ *
+ * It is the same seam every product uses; there is no CCU-Admin-only path and no privileged variant. A consumer
+ * that needs a governance read it does not find here extends THIS package for everyone, rather than hand-rolling
+ * a fetch — that is the whole point of the package existing.
+ *
+ * TYPES + THIN HTTP WRAPPERS ONLY. No policy logic lives here. Every authorization decision belongs to the
+ * Operator Gateway and the Control Plane behind it: the SDK never mints identity, never caches a decision, and
+ * never infers one. A caller supplies its own auth headers and the gateway decides.
+ *
+ * WHAT THE TYPES REFUSE TO FLATTEN, because the platform's own truth is not flat:
+ *
+ *   - `enforcement` on every Operative Type. The governed record declares more than the runtime consumes, so a
+ *     type that merged its fields would let a renderer show validated-but-unconsumed configuration as governance
+ *     in force. `enforced` and `declared` are separate lists, and `serving_envelope_source` names which authority
+ *     actually supplies the envelope that bounds a run — the record declares one and the enrollment declaration
+ *     is the one resolved at dispatch. Two truths, both reported.
+ *   - `operation_breadth` as {declared, effective, enforced}. An undeclared ceiling is stored as 0 and fails
+ *     closed to 1, so a single number would read as "no Operatives permitted" — the opposite of the truth.
+ *   - the authority envelope's `scope` and `excluded_terms`. What this reads is the Personality/consent HALF of
+ *     an Operation's authority; the re-proven initiating actor and the immutable Operation bounds are elsewhere.
+ *     A type called "the authority envelope" with seven flat arrays would describe an authority no commission
+ *     actually uses.
+ *   - `evaluated_at` + `evaluation: 'live_uncached_at_read'`. The envelope is a snapshot of a computation, never
+ *     stored state, and the type says so rather than trusting a renderer to remember.
+ */
+/** Base path of the Operator Gateway's admin surface. The gateway is the only thing this SDK talks to. */
+const BASE = '/api/v1/operator/admin';
+/**
+ * A structured non-2xx error carrying the request coordinates and nothing else.
+ *
+ * THE RAW UPSTREAM BODY IS NOT RETAINED — not on `.message`, not on any field. An upstream 500 can carry a stack
+ * trace, a DSN, or a token, and an error object is the single most widely-serialized value in a program: loggers
+ * serialize own properties, crash reporters ship the whole object, `JSON.stringify(err)` is idiomatic. Keeping
+ * the body "for a caller that explicitly needs it" makes every one of those paths a leak.
+ */
+export class AdminError extends Error {
+    constructor(method, path, status) {
+        super(`admin-sdk: ${method} ${path} → ${status}`);
+        this.name = 'AdminError';
+        this.status = status;
+        this.method = method;
+        this.path = path;
+    }
+}
+// ── The client ───────────────────────────────────────────────────────────────────────────────────
+/**
+ * AdminClient is a thin wrapper over the Operator Gateway's governance reads. Each method is one request; the
+ * gateway authorizes before proxying, and a non-2xx response throws.
+ *
+ * PRODUCT-OWNED READS CARRY BOTH HALVES OF THEIR IDENTITY on the path. A personality id or an operative id alone
+ * is ambiguous across products, and resolving one by picking a match would show a caller another product's
+ * governance — so the detail methods take (productId, id) and encode both.
+ */
+export class AdminClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, '');
+        this.headersFn = options.headers ?? (() => ({}));
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async request(method, path) {
+        const headers = { 'Content-Type': 'application/json', ...(await this.headersFn()) };
+        const resp = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers });
+        if (!resp.ok) {
+            // The body is deliberately not read: see AdminError.
+            throw new AdminError(method, path, resp.status);
+        }
+        return (await resp.json());
+    }
+    /** Every enrolled Project the operator may see. */
+    listEnrollments() {
+        return this.request('GET', `${BASE}/enrollments`);
+    }
+    /** One Project's enrollment record — its governed AI configuration. */
+    getEnrollment(productId) {
+        return this.request('GET', `${BASE}/enrollments/${encodeURIComponent(productId)}`);
+    }
+    /** The Project portfolio read. */
+    listProjects() {
+        return this.request('GET', `${BASE}/projects`);
+    }
+    /** The personalities the conductor is actually serving (the file registry). */
+    listPersonalities() {
+        return this.request('GET', `${BASE}/personalities`);
+    }
+    /** The governed Personality Records inside the operator's read scope, optionally narrowed to one product. */
+    listPersonalityRecords(productId) {
+        const q = productId ? `?product_id=${encodeURIComponent(productId)}` : '';
+        return this.request('GET', `${BASE}/personality-records${q}`);
+    }
+    /** One governed Personality Record and its version history. */
+    getPersonalityRecord(productId, personalityId) {
+        return this.request('GET', `${BASE}/personality-record/${encodeURIComponent(productId)}/${encodeURIComponent(personalityId)}`);
+    }
+    /**
+     * A Personality's effective authority, computed live at read time.
+     *
+     * The result is a snapshot of a computation, not stored state, and it covers the Personality/consent half of
+     * an Operation's authority only — the returned object names both facts about itself.
+     */
+    getAuthorityEnvelope(productId, personalityId) {
+        return this.request('GET', `${BASE}/personality-envelope/${encodeURIComponent(productId)}/${encodeURIComponent(personalityId)}`);
+    }
+    /**
+     * A product's Operative Type roster.
+     *
+     * `productId` NARROWS within the operator's authorized scope and can never widen it. This is deliberately not
+     * a platform-wide library view: "this product's Operatives" and "every Operative Type known to Universal" are
+     * different reads with different breadth, and only the first is this method.
+     */
+    listOperativeTypes(productId) {
+        return this.request('GET', `${BASE}/operative-types?product_id=${encodeURIComponent(productId)}`);
+    }
+    /** One Operative Type with its full version history. */
+    getOperativeType(productId, operativeId) {
+        return this.request('GET', `${BASE}/operative-type/${encodeURIComponent(productId)}/${encodeURIComponent(operativeId)}`);
+    }
+}
+/** Convenience factory, mirroring the other ConsciousClouds SDK clients. */
+export function createAdminClient(options) {
+    return new AdminClient(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@consciousclouds/admin-sdk",
+  "version": "0.1.0",
+  "description": "ConsciousClouds Universal Admin SDK \u2014 the thin, policy-free client for the Operator Gateway's governance reads: Projects/enrollment, Personalities and their governed records, effective authority envelopes, and Operative Type rosters. Types + HTTP wrappers only; every authorization decision belongs to the Operator Gateway and the Control Plane.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run clean && bun run build && bun run type-check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.2"
+  }
+}