@hypercerts-org/sdk-core 0.10.0-beta.4 → 0.10.0-beta.5

package/dist/index.cjs

@@ -3,9 +3,41 @@
 var oauthClientNode = require('@atproto/oauth-client-node');
 var zod = require('zod');
 var api = require('@atproto/api');
-var eventemitter3 = require('eventemitter3');
+var lexicon$1 = require('@atproto/lexicon');
 var lexicon = require('@hypercerts-org/lexicon');
-require('@atproto/lexicon');
+var eventemitter3 = require('eventemitter3');
+
+/**
+ * Type guard to check if a URL is a loopback address.
+ *
+ * Loopback addresses are used for local development and testing.
+ * They include localhost, 127.0.0.1, and [::1] (IPv6 loopback).
+ *
+ * @param url - The URL to check
+ * @returns True if the URL is a loopback address
+ *
+ * @example
+ * ```typescript
+ * isLoopbackUrl('http://localhost:3000'); // true
+ * isLoopbackUrl('http://127.0.0.1:8080'); // true
+ * isLoopbackUrl('http://[::1]:3000'); // true
+ * isLoopbackUrl('http://example.com'); // false
+ * isLoopbackUrl('https://localhost:3000'); // false (must be http)
+ * ```
+ */
+function isLoopbackUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "http:") {
+            return false;
+        }
+        const hostname = parsed.hostname.toLowerCase();
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
 
 /**
  * Base error class for all SDK errors.
@@ -599,24 +631,47 @@ const IdentityAttrSchema = zod.z.enum(["handle", "*"]);
 /**
  * Zod schema for MIME type patterns.
  *
- * Validates MIME type strings like "image/*" or "video/mp4".
+ * Validates MIME type strings used in blob permissions.
+ * Supports standard MIME types and wildcard patterns per ATProto spec.
+ *
+ * **References:**
+ * - ATProto Permission Spec: https://atproto.com/specs/permission (blob resource)
+ * - RFC 2045 (MIME): https://www.rfc-editor.org/rfc/rfc2045 (token definition)
+ * - IANA Media Types: https://www.iana.org/assignments/media-types/
+ *
+ * **Implementation:**
+ * This is a "good enough" validation that allows common real-world MIME types:
+ * - Type: letters, digits (e.g., "3gpp")
+ * - Subtype: letters, digits, hyphens, plus signs, dots, underscores, wildcards
+ * - Examples: "image/png", "application/vnd.api+json", "video/*", "clue_info+xml"
+ *
+ * Note: We use a simplified regex rather than full RFC 2045 token validation
+ * for practicality. Zod v4 has native MIME support (z.file().mime()) but would
+ * require a larger migration effort.
  *
  * @example
  * ```typescript
- * MimeTypeSchema.parse('image/*'); // Valid
- * MimeTypeSchema.parse('video/mp4'); // Valid
+ * MimeTypeSchema.parse('image/*'); // Valid - wildcard
+ * MimeTypeSchema.parse('video/mp4'); // Valid - standard
+ * MimeTypeSchema.parse('application/vnd.api+json'); // Valid - with dots/plus
  * MimeTypeSchema.parse('invalid'); // Throws ZodError
  * ```
  */
 const MimeTypeSchema = zod.z
     .string()
-    .regex(/^[a-z]+\/[a-z0-9*+-]+$/i, 'Invalid MIME type pattern. Expected format: type/subtype (e.g., "image/*" or "video/mp4")');
+    .regex(/^[a-z0-9]+\/[a-z0-9*+._-]+$/i, 'Invalid MIME type pattern. Expected format: type/subtype (e.g., "image/*", "video/mp4", "application/vnd.api+json")');
 /**
  * Zod schema for NSID (Namespaced Identifier).
  *
  * NSIDs are reverse-DNS style identifiers used throughout ATProto
  * (e.g., "app.bsky.feed.post" or "com.example.myrecord").
  *
+ * Official ATProto NSID spec requires:
+ * - Each segment must be 1-63 characters
+ * - Authority segments (all but last) can contain hyphens, but not at boundaries
+ * - Name segment (last) must start with a letter and contain only alphanumerics
+ * - Hyphens only allowed in authority segments, not in the name segment
+ *
  * @see https://atproto.com/specs/nsid
  *
  * @example
@@ -628,7 +683,7 @@ const MimeTypeSchema = zod.z
  */
 const NsidSchema = zod.z
     .string()
-    .regex(/^[a-zA-Z][a-zA-Z0-9-]*(\.[a-zA-Z][a-zA-Z0-9-]*)+$/, 'Invalid NSID format. Expected reverse-DNS format (e.g., "app.bsky.feed.post")');
+    .regex(/^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/, 'Invalid NSID format. Expected reverse-DNS format (e.g., "app.bsky.feed.post")');
 /**
  * Zod schema for account permission.
  *
@@ -1379,27 +1434,119 @@ const ScopePresets = {
 function parseScope(scope) {
     return scope.trim().split(/\s+/).filter(Boolean);
 }
+/**
+ * Helper function to match MIME type patterns with wildcard support.
+ *
+ * Implements MIME type matching for blob permissions per ATProto spec.
+ *
+ * **Reference:**
+ * - ATProto Permission Spec: https://atproto.com/specs/permission
+ *   Supports "MIME types or partial MIME type glob patterns"
+ *
+ * **Supported patterns:**
+ * - Exact matches: "image/png" matches "image/png"
+ * - Type wildcards: "image/*" matches "image/png", "image/jpeg", etc.
+ * - Full wildcards: `*` `/` `*` matches any MIME type
+ *
+ * @param pattern - The MIME type pattern (may contain wildcards)
+ * @param mimeType - The actual MIME type to check
+ * @returns True if the MIME type matches the pattern
+ *
+ * @example
+ * ```typescript
+ * matchMimePattern("image/*", "image/png"); // true
+ * matchMimePattern("*" + "/" + "*", "video/mp4"); // true - matches any MIME
+ * matchMimePattern("image/*", "video/mp4"); // false
+ * ```
+ */
+function matchMimePattern(pattern, mimeType) {
+    if (pattern === "*/*")
+        return true;
+    if (pattern === mimeType)
+        return true;
+    const [patternType, patternSubtype] = pattern.split("/");
+    const [mimeTypeType] = mimeType.split("/");
+    if (patternSubtype === "*" && patternType === mimeTypeType) {
+        return true;
+    }
+    return false;
+}
 /**
  * Check if a scope string contains a specific permission.
  *
- * This function performs exact string matching. For more advanced
- * permission checking (e.g., wildcard matching), you'll need to
- * implement custom logic.
+ * Implements permission matching per ATProto OAuth spec with support for
+ * exact matching and limited wildcard patterns.
+ *
+ * **References:**
+ * - ATProto Permission Spec: https://atproto.com/specs/permission
+ * - ATProto OAuth Spec: https://atproto.com/specs/oauth
+ *
+ * **Supported wildcards (per spec):**
+ * - `repo:*` - Matches any repository collection (e.g., `repo:app.bsky.feed.post`)
+ * - `rpc:*` - Matches any RPC lexicon (but aud cannot also be wildcard)
+ * - `blob:image/*` - MIME type wildcards (e.g., matches `blob:image/png`, `blob:image/jpeg`)
+ * - `blob:` + wildcard MIME - Matches any MIME type (using `*` + `/` + `*` pattern)
+ * - `identity:*` - Full control of DID document and handle (spec allows `*` as attr value)
+ *
+ * **NOT supported (per spec):**
+ * - `account:*` - Account attr does not support wildcards (only `email` and `repo` allowed)
+ * - `include:*` - Include NSID does not support wildcards
+ * - Partial wildcards like `com.example.*` are not supported
  *
  * @param scope - Space-separated scope string
  * @param permission - The permission to check for
  * @returns True if the scope contains the permission
  *
- * @example
+ * @example Exact matching
  * ```typescript
- * const scope = "account:email?action=read repo:app.bsky.feed.post";
- * hasPermission(scope, "account:email?action=read"); // true
+ * const scope = "account:email repo:app.bsky.feed.post";
+ * hasPermission(scope, "account:email"); // true
  * hasPermission(scope, "account:repo"); // false
  * ```
+ *
+ * @example Wildcard matching
+ * ```typescript
+ * const scope = "repo:* blob:image/* identity:*";
+ * hasPermission(scope, "repo:app.bsky.feed.post"); // true
+ * hasPermission(scope, "blob:image/png"); // true
+ * hasPermission(scope, "blob:video/mp4"); // false
+ * hasPermission(scope, "identity:handle"); // true
+ * ```
  */
 function hasPermission(scope, permission) {
     const permissions = parseScope(scope);
-    return permissions.includes(permission);
+    // 1. Check exact match first
+    if (permissions.includes(permission)) {
+        return true;
+    }
+    // 2. Check wildcard matches (only those supported by ATProto spec)
+    for (const scopePermission of permissions) {
+        // repo:* - Wildcard for repository collections
+        // Spec: "Wildcard (*) is allowed in scope string syntax"
+        if (scopePermission.startsWith("repo:*") && permission.startsWith("repo:")) {
+            return true;
+        }
+        // rpc:* - Wildcard for RPC lexicons
+        // Spec: "Wildcard (*) is allowed in scope string syntax for lxm parameter"
+        if (scopePermission.startsWith("rpc:*") && permission.startsWith("rpc:")) {
+            return true;
+        }
+        // blob MIME wildcards - image/*, video/*, or full wildcard
+        // Spec: "MIME types or partial MIME type glob patterns"
+        if (scopePermission.startsWith("blob:") && permission.startsWith("blob:")) {
+            const scopeMime = scopePermission.substring(5).split("?")[0]; // Remove "blob:" prefix and query params
+            const permMime = permission.substring(5).split("?")[0];
+            if (matchMimePattern(scopeMime, permMime)) {
+                return true;
+            }
+        }
+        // identity:* - Full control of DID document and handle
+        // Spec: "* - Full control of DID document and handle" (as attr value)
+        if (scopePermission === "identity:*" && permission.startsWith("identity:")) {
+            return true;
+        }
+    }
+    return false;
 }
 /**
  * Check if a scope string contains all of the specified permissions.
@@ -1623,6 +1770,26 @@ class OAuthClient {
     async getClient() {
         return this.clientPromise;
     }
+    /**
+     * Detects if a URL is a loopback address (localhost or 127.0.0.1 or [::1]).
+     *
+     * @param urlString - The URL to check
+     * @returns True if the URL is an HTTP loopback address
+     * @internal
+     */
+    isLoopbackUrl(urlString) {
+        try {
+            const url = new URL(urlString);
+            if (url.protocol !== "http:") {
+                return false;
+            }
+            const hostname = url.hostname.toLowerCase();
+            return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Builds OAuth client metadata from configuration.
      *
@@ -1641,6 +1808,23 @@ class OAuthClient {
      */
     buildClientMetadata() {
         const clientIdUrl = new URL(this.config.oauth.clientId);
+        // Detect and warn about loopback configuration
+        const isDevelopment = isLoopbackUrl(this.config.oauth.clientId) || isLoopbackUrl(this.config.oauth.redirectUri);
+        if (isDevelopment && !this.config.oauth.developmentMode) {
+            this.logger?.warn("Using HTTP loopback URLs without explicit developmentMode flag", {
+                clientId: this.config.oauth.clientId,
+                redirectUri: this.config.oauth.redirectUri,
+                note: "This is suitable for local development only. For production, use HTTPS URLs.",
+                recommendation: "Set oauth.developmentMode: true to suppress this warning.",
+            });
+        }
+        if (isDevelopment) {
+            this.logger?.info("Running in development mode with loopback URLs", {
+                clientId: this.config.oauth.clientId,
+                redirectUri: this.config.oauth.redirectUri,
+                note: "Authorization server must support loopback clients (optional per AT Protocol spec)",
+            });
+        }
         const metadata = {
             client_id: this.config.oauth.clientId,
             client_name: "ATProto SDK Client",
@@ -2078,6 +2262,299 @@ class ConfigurableAgent extends api.Agent {
     }
 }
 
+/**
+ * LexiconRegistry - Manages custom lexicon registration and validation.
+ *
+ * This module provides a registry for AT Protocol lexicon schemas,
+ * allowing developers to register custom lexicons and validate records
+ * against registered schemas.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Registry for managing AT Protocol lexicon schemas.
+ *
+ * The LexiconRegistry allows developers to:
+ * - Register custom lexicon definitions
+ * - Validate records against registered schemas
+ * - Query registered lexicons
+ * - Add lexicons to AT Protocol agents
+ *
+ * @example Basic usage
+ * ```typescript
+ * const registry = new LexiconRegistry();
+ *
+ * // Register a custom lexicon
+ * registry.register({
+ *   lexicon: 1,
+ *   id: "org.myapp.customRecord",
+ *   defs: {
+ *     main: {
+ *       type: "record",
+ *       key: "tid",
+ *       record: {
+ *         type: "object",
+ *         required: ["$type", "title"],
+ *         properties: {
+ *           "$type": { type: "string", const: "org.myapp.customRecord" },
+ *           title: { type: "string" }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Validate a record
+ * const result = registry.validate("org.myapp.customRecord", {
+ *   $type: "org.myapp.customRecord",
+ *   title: "My Record"
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+class LexiconRegistry {
+    /**
+     * Creates a new LexiconRegistry instance.
+     *
+     * @param initialLexicons - Optional array of lexicons to register on initialization
+     */
+    constructor(initialLexicons) {
+        this.lexicons = new lexicon$1.Lexicons();
+        this.registeredIds = new Set();
+        if (initialLexicons && initialLexicons.length > 0) {
+            this.registerMany(initialLexicons);
+        }
+    }
+    /**
+     * Registers a single lexicon definition.
+     *
+     * @param lexicon - The lexicon document to register
+     * @throws {Error} If the lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.customRecord",
+     *   defs: { ... }
+     * });
+     * ```
+     */
+    register(lexicon) {
+        if (!lexicon.id) {
+            throw new Error("Lexicon must have an id");
+        }
+        if (this.registeredIds.has(lexicon.id)) {
+            throw new Error(`Lexicon ${lexicon.id} is already registered`);
+        }
+        try {
+            // Check if the lexicon already exists in the internal store
+            // (e.g., after unregister which only removes from registeredIds)
+            const existingLexicon = this.lexicons.get(lexicon.id);
+            if (!existingLexicon) {
+                // Lexicon is truly new, add it to the store
+                this.lexicons.add(lexicon);
+            }
+            // Always add to registeredIds (re-enable if previously unregistered)
+            this.registeredIds.add(lexicon.id);
+        }
+        catch (error) {
+            throw new Error(`Failed to register lexicon ${lexicon.id}: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    }
+    /**
+     * Registers multiple lexicon definitions at once.
+     *
+     * @param lexicons - Array of lexicon documents to register
+     * @throws {Error} If any lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * registry.registerMany([lexicon1, lexicon2, lexicon3]);
+     * ```
+     */
+    registerMany(lexicons) {
+        for (const lexicon of lexicons) {
+            this.register(lexicon);
+        }
+    }
+    /**
+     * Registers a lexicon from a JSON object.
+     *
+     * This is a convenience method for registering lexicons loaded from JSON files.
+     *
+     * @param lexiconJson - The lexicon as a plain JavaScript object
+     * @throws {ValidationError} If the lexicon is not a valid object
+     * @throws {Error} If the lexicon is invalid or already registered
+     *
+     * @example
+     * ```typescript
+     * import customLexicon from "./custom-lexicon.json";
+     * registry.registerFromJSON(customLexicon);
+     * ```
+     */
+    registerFromJSON(lexiconJson) {
+        // Validate that input is an object and not null
+        if (typeof lexiconJson !== "object" || lexiconJson === null) {
+            throw new ValidationError("Lexicon JSON must be a valid object");
+        }
+        // Now we can safely cast to LexiconDoc and register
+        this.register(lexiconJson);
+    }
+    /**
+     * Unregisters a lexicon by its NSID.
+     *
+     * @param nsid - The NSID of the lexicon to unregister
+     * @returns True if the lexicon was unregistered, false if it wasn't registered
+     *
+     * @example
+     * ```typescript
+     * registry.unregister("org.myapp.customRecord");
+     * ```
+     */
+    unregister(nsid) {
+        if (!this.registeredIds.has(nsid)) {
+            return false;
+        }
+        this.registeredIds.delete(nsid);
+        // Note: Lexicons class doesn't have a remove method,
+        // so we can't actually remove from the internal store.
+        // We track removal in our Set for isRegistered checks.
+        return true;
+    }
+    /**
+     * Checks if a lexicon is registered.
+     *
+     * @param nsid - The NSID to check
+     * @returns True if the lexicon is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.isRegistered("org.myapp.customRecord")) {
+     *   // Lexicon is available
+     * }
+     * ```
+     */
+    isRegistered(nsid) {
+        return this.registeredIds.has(nsid);
+    }
+    /**
+     * Gets a lexicon definition by its NSID.
+     *
+     * @param nsid - The NSID of the lexicon to retrieve
+     * @returns The lexicon document, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const lexicon = registry.get("org.myapp.customRecord");
+     * if (lexicon) {
+     *   console.log(lexicon.defs);
+     * }
+     * ```
+     */
+    get(nsid) {
+        if (!this.isRegistered(nsid)) {
+            return undefined;
+        }
+        return this.lexicons.get(nsid);
+    }
+    /**
+     * Gets all registered lexicon NSIDs.
+     *
+     * @returns Array of registered NSIDs
+     *
+     * @example
+     * ```typescript
+     * const registered = registry.getAll();
+     * console.log(`Registered lexicons: ${registered.join(", ")}`);
+     * ```
+     */
+    getAll() {
+        return Array.from(this.registeredIds);
+    }
+    /**
+     * Validates a record against a registered lexicon.
+     *
+     * @param nsid - The collection NSID to validate against
+     * @param record - The record data to validate
+     * @returns Validation result with success status and optional error message
+     *
+     * @example
+     * ```typescript
+     * const result = registry.validate("org.myapp.customRecord", {
+     *   $type: "org.myapp.customRecord",
+     *   title: "My Record"
+     * });
+     *
+     * if (!result.valid) {
+     *   console.error(`Validation failed: ${result.error}`);
+     * }
+     * ```
+     */
+    validate(nsid, record) {
+        if (!this.isRegistered(nsid)) {
+            return {
+                valid: false,
+                error: `Lexicon ${nsid} is not registered`,
+            };
+        }
+        try {
+            this.lexicons.assertValidRecord(nsid, record);
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : "Validation failed",
+            };
+        }
+    }
+    /**
+     * Adds all registered lexicons to an AT Protocol Agent.
+     *
+     * This method is currently a no-op as the AT Protocol Agent
+     * doesn't provide a public API for adding lexicons at runtime.
+     * Lexicons must be registered with the server.
+     *
+     * This method is kept for future compatibility if the API
+     * adds support for client-side lexicon registration.
+     *
+     * @param _agent - The AT Protocol Agent (currently unused)
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent(session);
+     * registry.addToAgent(agent);
+     * // Reserved for future use
+     * ```
+     */
+    addToAgent(_agent) {
+        // No-op: AT Protocol Agent doesn't support client-side lexicon addition
+        // Lexicons are validated client-side via this registry,
+        // but server-side validation is performed by the PDS/SDS
+    }
+    /**
+     * Gets the underlying Lexicons instance.
+     *
+     * This provides direct access to the AT Protocol Lexicons object
+     * for advanced use cases.
+     *
+     * @returns The internal Lexicons instance
+     *
+     * @example
+     * ```typescript
+     * const lexicons = registry.getLexicons();
+     * // Use lexicons directly for advanced operations
+     * ```
+     */
+    getLexicons() {
+        return this.lexicons;
+    }
+}
+
 /**
  * RecordOperationsImpl - Low-level record CRUD operations.
  *
@@ -2132,12 +2609,14 @@ class RecordOperationsImpl {
      *
      * @param agent - AT Protocol Agent for making API calls
      * @param repoDid - DID of the repository to operate on
+     * @param lexiconRegistry - Optional registry for validating records against lexicon schemas
      *
      * @internal
      */
-    constructor(agent, repoDid) {
+    constructor(agent, repoDid, lexiconRegistry) {
         this.agent = agent;
         this.repoDid = repoDid;
+        this.lexiconRegistry = lexiconRegistry;
     }
     /**
      * Creates a new record in the specified collection.
@@ -2147,14 +2626,17 @@ class RecordOperationsImpl {
      * @param params.record - Record data conforming to the collection's lexicon schema
      * @param params.rkey - Optional record key. If not provided, a TID (timestamp-based ID)
      *                      is automatically generated by the server.
+     * @param params.skipValidation - Optional flag to skip lexicon validation (default: false)
      * @returns Promise resolving to the created record's URI and CID
      * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
      * @throws {@link NetworkError} if the API request fails
      *
      * @remarks
      * The record is validated against the collection's lexicon before sending
-     * to the server. If no lexicon is registered for the collection, validation
-     * is skipped (allowing custom record types).
+     * to the server if the collection is registered in the LexiconRegistry.
+     * If no lexicon is registered for the collection, validation is skipped
+     * (allowing custom record types). Use `skipValidation: true` to bypass
+     * validation even for registered collections.
      *
      * **AT-URI Format**: `at://{did}/{collection}/{rkey}`
      *
@@ -2174,6 +2656,13 @@ class RecordOperationsImpl {
      */
     async create(params) {
         try {
+            // Validate record against registered lexicon if available
+            if (!params.skipValidation && this.lexiconRegistry?.isRegistered(params.collection)) {
+                const validation = this.lexiconRegistry.validate(params.collection, params.record);
+                if (!validation.valid) {
+                    throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
+                }
+            }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
                 collection: params.collection,
@@ -2198,6 +2687,7 @@ class RecordOperationsImpl {
      * @param params.collection - NSID of the collection
      * @param params.rkey - Record key (the last segment of the AT-URI)
      * @param params.record - New record data (completely replaces existing record)
+     * @param params.skipValidation - Optional flag to skip lexicon validation (default: false)
      * @returns Promise resolving to the updated record's URI and new CID
      * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
      * @throws {@link NetworkError} if the API request fails
@@ -2207,6 +2697,10 @@ class RecordOperationsImpl {
      * record is replaced with the new data. To preserve existing fields,
      * first fetch the record with {@link get}, modify it, then update.
      *
+     * The record is validated against the collection's lexicon before sending
+     * to the server if the collection is registered in the LexiconRegistry.
+     * Use `skipValidation: true` to bypass validation.
+     *
      * @example
      * ```typescript
      * // Get existing record
@@ -2228,6 +2722,13 @@ class RecordOperationsImpl {
      */
     async update(params) {
         try {
+            // Validate record against registered lexicon if available
+            if (!params.skipValidation && this.lexiconRegistry?.isRegistered(params.collection)) {
+                const validation = this.lexiconRegistry.validate(params.collection, params.record);
+                if (!validation.valid) {
+                    throw new ValidationError(`Invalid record for collection ${params.collection}: ${validation.error}`);
+                }
+            }
             const result = await this.agent.com.atproto.repo.putRecord({
                 repo: this.repoDid,
                 collection: params.collection,
@@ -2884,20 +3385,21 @@ class ProfileOperationsImpl {
 const HYPERCERT_LEXICONS = [
     lexicon.CERTIFIED_DEFS_LEXICON_JSON,
     lexicon.LOCATION_LEXICON_JSON,
-    lexicon.STRONGREF_LEXICON_JSON,
+    lexicon.STRONG_REF_LEXICON_JSON,
     lexicon.HYPERCERTS_DEFS_LEXICON_JSON,
     lexicon.ACTIVITY_LEXICON_JSON,
     lexicon.COLLECTION_LEXICON_JSON,
-    lexicon.CONTRIBUTION_LEXICON_JSON,
+    lexicon.CONTRIBUTION_DETAILS_LEXICON_JSON,
+    lexicon.CONTRIBUTOR_INFORMATION_LEXICON_JSON,
     lexicon.EVALUATION_LEXICON_JSON,
     lexicon.EVIDENCE_LEXICON_JSON,
     lexicon.MEASUREMENT_LEXICON_JSON,
     lexicon.RIGHTS_LEXICON_JSON,
-    lexicon.PROJECT_LEXICON_JSON,
     lexicon.BADGE_AWARD_LEXICON_JSON,
     lexicon.BADGE_DEFINITION_LEXICON_JSON,
     lexicon.BADGE_RESPONSE_LEXICON_JSON,
     lexicon.FUNDING_RECEIPT_LEXICON_JSON,
+    lexicon.WORK_SCOPE_TAG_LEXICON_JSON,
 ];
 /**
  * Collection NSIDs (Namespaced Identifiers) for hypercert records.
@@ -2919,9 +3421,15 @@ const HYPERCERT_COLLECTIONS = {
      */
     LOCATION: lexicon.LOCATION_NSID,
     /**
-     * Contribution record collection.
+     * Contribution details record collection.
+     * For storing details about a specific contribution (role, description, timeframe).
      */
-    CONTRIBUTION: lexicon.CONTRIBUTION_NSID,
+    CONTRIBUTION_DETAILS: lexicon.CONTRIBUTION_DETAILS_NSID,
+    /**
+     * Contributor information record collection.
+     * For storing contributor profile information (identifier, displayName, image).
+     */
+    CONTRIBUTOR_INFORMATION: lexicon.CONTRIBUTOR_INFORMATION_NSID,
     /**
      * Measurement record collection.
      */
@@ -2936,12 +3444,9 @@ const HYPERCERT_COLLECTIONS = {
     EVIDENCE: lexicon.EVIDENCE_NSID,
     /**
      * Collection record collection (groups of hypercerts).
+     * Projects are now collections with type='project'.
      */
     COLLECTION: lexicon.COLLECTION_NSID,
-    /**
-     * Project record collection.
-     */
-    PROJECT: lexicon.PROJECT_NSID,
     /**
      * Badge award record collection.
      */
@@ -2958,6 +3463,11 @@ const HYPERCERT_COLLECTIONS = {
      * Funding receipt record collection.
      */
     FUNDING_RECEIPT: lexicon.FUNDING_RECEIPT_NSID,
+    /**
+     * Work scope tag record collection.
+     * For defining reusable work scope atoms.
+     */
+    WORK_SCOPE_TAG: lexicon.WORK_SCOPE_TAG_NSID,
 };
 
 /**
@@ -3051,6 +3561,26 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             }
         }
     }
+    /**
+     * Helper function to upload a blob to the repository, returns a blob reference
+     *
+     * @param content - Blob to upload
+     * @param fallbackContentType | if content.type is empty,we use this
+     * @returns BlobRef
+     * @throws {@link NetworkError} if upload fails
+     * @internal
+     */
+    async handleBlobUpload(content, fallbackContentType) {
+        const arrayBuffer = await content.arrayBuffer();
+        const uint8Array = new Uint8Array(arrayBuffer);
+        const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+            encoding: content.type || fallbackContentType,
+        });
+        if (!uploadResult.success) {
+            throw new NetworkError("Failed to upload blob");
+        }
+        return uploadResult.data.blob;
+    }
     /**
      * Uploads an image blob and returns a blob reference.
      *
@@ -3161,9 +3691,6 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         if (imageBlobRef) {
             hypercertRecord.image = imageBlobRef;
         }
-        if (params.evidence && params.evidence.length > 0) {
-            hypercertRecord.evidence = params.evidence;
-        }
         const hypercertValidation = lexicon.validate(hypercertRecord, HYPERCERT_COLLECTIONS.CLAIM, "main", false);
         if (!hypercertValidation.success) {
             throw new ValidationError(`Invalid hypercert record: ${hypercertValidation.error?.message}`);
@@ -3247,6 +3774,35 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             throw error;
         }
     }
+    /**
+     * Creates evidence records with progress tracking.
+     *
+     * @param hypercertUri - URI of the hypercert
+     * @param evidenceItems - Array of evidence data (without subjectUri)
+     * @param onProgress - Optional progress callback
+     * @returns Promise resolving to array of evidence URIs
+     * @internal
+     */
+    async createEvidenceWithProgress(hypercertUri, evidenceItems, onProgress) {
+        this.emitProgress(onProgress, { name: "addEvidence", status: "start" });
+        try {
+            const evidenceUris = await Promise.all(evidenceItems.map((evidence) => this.addEvidence({
+                subjectUri: hypercertUri,
+                ...evidence,
+            }).then((result) => result.uri)));
+            this.emitProgress(onProgress, {
+                name: "addEvidence",
+                status: "success",
+                data: { count: evidenceUris.length },
+            });
+            return evidenceUris;
+        }
+        catch (error) {
+            this.emitProgress(onProgress, { name: "addEvidence", status: "error", error: error });
+            this.logger?.warn(`Failed to create evidence: ${error instanceof Error ? error.message : "Unknown"}`);
+            throw error;
+        }
+    }
     /**
      * Creates a new hypercert with all related records.
      *
@@ -3275,6 +3831,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * - `createHypercert`: Main hypercert record creation
      * - `attachLocation`: Location record creation
      * - `createContributions`: Contribution records creation
+     * - `addEvidence`: Evidence records creation
      *
      * @example Minimal hypercert
      * ```typescript
@@ -3350,6 +3907,15 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
                     // Error already logged and progress emitted
                 }
             }
+            // Step 6: Add evidence records if provided
+            if (params.evidence && params.evidence.length > 0) {
+                try {
+                    result.evidenceUris = await this.createEvidenceWithProgress(hypercertUri, params.evidence, params.onProgress);
+                }
+                catch {
+                    // Error already logged and progress emitted
+                }
+            }
             return result;
         }
         catch (error) {
@@ -3632,50 +4198,18 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      */
     async attachLocation(hypercertUri, location) {
         try {
-            // Validate required srs field
             if (!location.srs) {
                 throw new ValidationError("srs (Spatial Reference System) is required. Example: 'EPSG:4326' for WGS84 coordinates, or 'http://www.opengis.net/def/crs/OGC/1.3/CRS84' for CRS84.");
             }
             // Validate that hypercert exists (unused but confirms hypercert is valid)
             await this.get(hypercertUri);
             const createdAt = new Date().toISOString();
-            // Determine location type and prepare location data
-            let locationData;
-            let locationType;
-            if (location.geojson) {
-                // Upload GeoJSON as a blob
-                const arrayBuffer = await location.geojson.arrayBuffer();
-                const uint8Array = new Uint8Array(arrayBuffer);
-                const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-                    encoding: location.geojson.type || "application/geo+json",
-                });
-                if (uploadResult.success) {
-                    locationData = {
-                        $type: "blob",
-                        ref: { $link: uploadResult.data.blob.ref.toString() },
-                        mimeType: uploadResult.data.blob.mimeType,
-                        size: uploadResult.data.blob.size,
-                    };
-                    locationType = "geojson-point";
-                }
-                else {
-                    throw new NetworkError("Failed to upload GeoJSON blob");
-                }
-            }
-            else {
-                // Use value as a URI reference
-                locationData = {
-                    $type: "org.hypercerts.defs#uri",
-                    uri: location.value,
-                };
-                locationType = "coordinate-decimal";
-            }
-            // Build location record according to app.certified.location lexicon
+            const locationData = await this.resolveUriOrBlob(location.location, "application/geo+json");
             const locationRecord = {
                 $type: HYPERCERT_COLLECTIONS.LOCATION,
-                lpVersion: "1.0",
+                lpVersion: location.lpVersion || "1.0",
                 srs: location.srs,
-                locationType,
+                locationType: location.locationType,
                 location: locationData,
                 createdAt,
                 name: location.name,
@@ -3693,6 +4227,16 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             if (!result.success) {
                 throw new NetworkError("Failed to attach location");
             }
+            await this.update({
+                uri: hypercertUri,
+                updates: {
+                    location: {
+                        $type: "com.atproto.repo.strongRef",
+                        uri: result.data.uri,
+                        cid: result.data.cid,
+                    },
+                },
+            });
             this.emit("locationAttached", { uri: result.data.uri, cid: result.data.cid, hypercertUri });
             return { uri: result.data.uri, cid: result.data.cid };
         }
@@ -3703,36 +4247,75 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         }
     }
     /**
-     * Adds evidence to an existing hypercert.
+     * Generic helper to resolve string | Blob into a URI or blob reference.
+     *
+     * @param content - Either a URI string or a Blob to upload
+     * @param fallbackMimeType - MIME type to use if Blob.type is empty
+     * @returns Promise resolving to either a URI ref or blob ref union type
+     * @internal
+     */
+    async resolveUriOrBlob(content, fallbackMimeType) {
+        if (typeof content === "string") {
+            return {
+                $type: "org.hypercerts.defs#uri",
+                uri: content,
+            };
+        }
+        else {
+            const uploadedBlob = await this.handleBlobUpload(content, fallbackMimeType);
+            return {
+                $type: "org.hypercerts.defs#smallBlob",
+                blob: uploadedBlob,
+            };
+        }
+    }
+    /**
+     * Adds evidence to any subject via the subject ref.
      *
-     * @param hypercertUri - AT-URI of the hypercert
-     * @param evidence - Array of evidence items to add
+     * @param evidence - HypercertEvidenceInput
      * @returns Promise resolving to update result
      * @throws {@link ValidationError} if validation fails
      * @throws {@link NetworkError} if the operation fails
      *
-     * @remarks
-     * Evidence is appended to existing evidence, not replaced.
-     *
      * @example
      * ```typescript
-     * await repo.hypercerts.addEvidence(hypercertUri, [
-     *   { uri: "https://example.com/report.pdf", description: "Impact report" },
-     *   { uri: "https://example.com/data.csv", description: "Raw data" },
-     * ]);
+     * await repo.hypercerts.addEvidence({
+     *   subjectUri: "at://did:plc:u7h3dstby64di67bxaotzxcz/org.hypercerts.claim.activity/3mbvv5d7ixh2g"
+     *   content: Blob,
+     *   title: "Meeting Notes",
+     *   shortDescription: "Meetings notes from the 3rd of December 2025",
+     *   description: "The meeting with the board of directors and audience on 2025 in regards to the ecological landscape",
+     *   relationType: "supports",
+     * })
      * ```
      */
-    async addEvidence(hypercertUri, evidence) {
+    async addEvidence(evidence) {
         try {
-            const existing = await this.get(hypercertUri);
-            const existingEvidence = existing.record.evidence || [];
-            const updatedEvidence = [...existingEvidence, ...evidence];
-            const result = await this.update({
-                uri: hypercertUri,
-                updates: { evidence: updatedEvidence },
+            const { subjectUri, content, ...rest } = evidence;
+            const subject = await this.get(subjectUri);
+            const createdAt = new Date().toISOString();
+            const evidenceContent = await this.resolveUriOrBlob(content, "application/octet-stream");
+            const evidenceRecord = {
+                ...rest,
+                $type: HYPERCERT_COLLECTIONS.EVIDENCE,
+                createdAt,
+                content: evidenceContent,
+                subject: { uri: subject.uri, cid: subject.cid },
+            };
+            const validation = lexicon.validate(evidenceRecord, HYPERCERT_COLLECTIONS.EVIDENCE, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid evidence record: ${validation.error?.message}`);
+            }
+            const result = await this.agent.com.atproto.repo.createRecord({
+                repo: this.repoDid,
+                collection: HYPERCERT_COLLECTIONS.EVIDENCE,
+                record: evidenceRecord,
             });
-            this.emit("evidenceAdded", { uri: result.uri, cid: result.cid });
-            return result;
+            if (!result.success) {
+                throw new NetworkError(`Failed to add evidence`);
+            }
+            this.emit("evidenceAdded", { uri: result.data.uri, cid: result.data.cid });
+            return { uri: result.data.uri, cid: result.data.cid };
         }
         catch (error) {
             if (error instanceof ValidationError || error instanceof NetworkError)
@@ -3741,22 +4324,29 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         }
     }
     /**
-     * Creates a contribution record.
+     * Creates a contribution details record.
+     *
+     * This creates a standalone contribution details record that can be referenced
+     * from an activity's `contributors` array via a strong reference.
      *
      * @param params - Contribution parameters
-     * @param params.hypercertUri - Optional hypercert to link (can be standalone)
-     * @param params.contributors - Array of contributor DIDs
-     * @param params.role - Role of the contributors (e.g., "coordinator", "implementer")
+     * @param params.hypercertUri - Optional hypercert (unused, kept for backward compatibility)
+     * @param params.contributors - Array of contributor DIDs (unused, kept for backward compatibility)
+     * @param params.role - Role of the contributor (e.g., "coordinator", "implementer")
      * @param params.description - Optional description of the contribution
-     * @returns Promise resolving to contribution record URI and CID
+     * @returns Promise resolving to contribution details record URI and CID
      * @throws {@link ValidationError} if validation fails
      * @throws {@link NetworkError} if the operation fails
      *
+     * @remarks
+     * In the new lexicon structure, contributions are stored differently:
+     * - Use `contributionDetails` for detailed contribution records (role, description, timeframe)
+     * - Use `contributorInformation` for contributor profiles (identifier, displayName, image)
+     * - Reference these from the activity's `contributors` array using strong refs
+     *
      * @example
      * ```typescript
      * await repo.hypercerts.addContribution({
-     *   hypercertUri: hypercertUri,
-     *   contributors: ["did:plc:alice", "did:plc:bob"],
      *   role: "implementer",
      *   description: "On-ground implementation team",
      * });
@@ -3766,28 +4356,22 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
         try {
             const createdAt = new Date().toISOString();
             const contributionRecord = {
-                $type: HYPERCERT_COLLECTIONS.CONTRIBUTION,
-                contributors: params.contributors,
+                $type: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
                 role: params.role,
                 createdAt,
-                description: params.description,
-                hypercert: { uri: "", cid: "" }, // Will be set below if hypercertUri provided
+                contributionDescription: params.description,
             };
-            if (params.hypercertUri) {
-                const hypercert = await this.get(params.hypercertUri);
-                contributionRecord.hypercert = { uri: hypercert.uri, cid: hypercert.cid };
-            }
-            const validation = lexicon.validate(contributionRecord, HYPERCERT_COLLECTIONS.CONTRIBUTION, "main", false);
+            const validation = lexicon.validate(contributionRecord, HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS, "main", false);
             if (!validation.success) {
-                throw new ValidationError(`Invalid contribution record: ${validation.error?.message}`);
+                throw new ValidationError(`Invalid contribution details record: ${validation.error?.message}`);
             }
             const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
-                collection: HYPERCERT_COLLECTIONS.CONTRIBUTION,
+                collection: HYPERCERT_COLLECTIONS.CONTRIBUTION_DETAILS,
                 record: contributionRecord,
             });
             if (!result.success) {
-                throw new NetworkError("Failed to create contribution");
+                throw new NetworkError("Failed to create contribution details");
             }
             this.emit("contributionCreated", { uri: result.data.uri, cid: result.data.cid });
             return { uri: result.data.uri, cid: result.data.cid };
@@ -3924,7 +4508,7 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      * @param params.title - Collection title
      * @param params.claims - Array of hypercert references with weights
      * @param params.shortDescription - Optional short description
-     * @param params.coverPhoto - Optional cover image blob
+     * @param params.banner - Optional cover image blob
      * @returns Promise resolving to collection record URI and CID
      * @throws {@link ValidationError} if validation fails
      * @throws {@link NetworkError} if the operation fails
@@ -3939,22 +4523,22 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
      *     { uri: hypercert2Uri, cid: hypercert2Cid, weight: "0.3" },
      *     { uri: hypercert3Uri, cid: hypercert3Cid, weight: "0.2" },
      *   ],
-     *   coverPhoto: coverImageBlob,
+     *   banner: coverImageBlob,
      * });
      * ```
      */
     async createCollection(params) {
         try {
             const createdAt = new Date().toISOString();
-            let coverPhotoRef;
-            if (params.coverPhoto) {
-                const arrayBuffer = await params.coverPhoto.arrayBuffer();
+            let bannerRef;
+            if (params.banner) {
+                const arrayBuffer = await params.banner.arrayBuffer();
                 const uint8Array = new Uint8Array(arrayBuffer);
                 const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
-                    encoding: params.coverPhoto.type || "image/jpeg",
+                    encoding: params.banner.type || "image/jpeg",
                 });
                 if (uploadResult.success) {
-                    coverPhotoRef = {
+                    bannerRef = {
                         $type: "blob",
                         ref: { $link: uploadResult.data.blob.ref.toString() },
                         mimeType: uploadResult.data.blob.mimeType,
@@ -3971,8 +4555,8 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             if (params.shortDescription) {
                 collectionRecord.shortDescription = params.shortDescription;
             }
-            if (coverPhotoRef) {
-                collectionRecord.coverPhoto = coverPhotoRef;
+            if (bannerRef) {
+                collectionRecord.banner = bannerRef;
             }
             const validation = lexicon.validate(collectionRecord, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
             if (!validation.success) {
@@ -4083,190 +4667,606 @@ class HypercertOperationsImpl extends eventemitter3.EventEmitter {
             throw new NetworkError(`Failed to list collections: ${error instanceof Error ? error.message : "Unknown"}`, error);
         }
     }
-}
-
-/**
- * CollaboratorOperationsImpl - SDS collaborator management operations.
- *
- * This module provides the implementation for managing collaborator
- * access on Shared Data Server (SDS) repositories.
- *
- * @packageDocumentation
- */
-/**
- * Implementation of collaborator operations for SDS access control.
- *
- * This class manages access permissions for shared repositories on
- * Shared Data Servers (SDS). It provides role-based access control
- * with predefined permission sets.
- *
- * @remarks
- * This class is typically not instantiated directly. Access it through
- * {@link Repository.collaborators} on an SDS-connected repository.
- *
- * **Role Hierarchy**:
- * - `viewer`: Read-only access
- * - `editor`: Read + Create + Update
- * - `admin`: All permissions except ownership transfer
- * - `owner`: Full control including ownership management
- *
- * **SDS API Endpoints Used**:
- * - `com.sds.repo.grantAccess`: Grant access to a user
- * - `com.sds.repo.revokeAccess`: Revoke access from a user
- * - `com.sds.repo.listCollaborators`: List all collaborators
- * - `com.sds.repo.getPermissions`: Get current user's permissions
- * - `com.sds.repo.transferOwnership`: Transfer repository ownership
- *
- * @example
- * ```typescript
- * // Get SDS repository
- * const sdsRepo = sdk.repository(session, { server: "sds" });
- *
- * // Grant editor access
- * await sdsRepo.collaborators.grant({
- *   userDid: "did:plc:new-user",
- *   role: "editor",
- * });
- *
- * // List all collaborators
- * const collaborators = await sdsRepo.collaborators.list();
- *
- * // Check specific user
- * const hasAccess = await sdsRepo.collaborators.hasAccess("did:plc:someone");
- * const role = await sdsRepo.collaborators.getRole("did:plc:someone");
- * ```
- *
- * @internal
- */
-class CollaboratorOperationsImpl {
-    /**
-     * Creates a new CollaboratorOperationsImpl.
-     *
-     * @param session - Authenticated OAuth session with fetchHandler
-     * @param repoDid - DID of the repository to manage
-     * @param serverUrl - SDS server URL
-     *
-     * @internal
-     */
-    constructor(session, repoDid, serverUrl) {
-        this.session = session;
-        this.repoDid = repoDid;
-        this.serverUrl = serverUrl;
-    }
-    /**
-     * Converts a role to its corresponding permissions object.
-     *
-     * @param role - The role to convert
-     * @returns Permission flags for the role
-     * @internal
-     */
-    roleToPermissions(role) {
-        switch (role) {
-            case "viewer":
-                return { read: true, create: false, update: false, delete: false, admin: false, owner: false };
-            case "editor":
-                return { read: true, create: true, update: true, delete: false, admin: false, owner: false };
-            case "admin":
-                return { read: true, create: true, update: true, delete: true, admin: true, owner: false };
-            case "owner":
-                return { read: true, create: true, update: true, delete: true, admin: true, owner: true };
-        }
-    }
-    /**
-     * Determines the role from a permissions object.
-     *
-     * @param permissions - The permissions to analyze
-     * @returns The highest role matching the permissions
-     * @internal
-     */
-    permissionsToRole(permissions) {
-        if (permissions.owner)
-            return "owner";
-        if (permissions.admin)
-            return "admin";
-        if (permissions.create || permissions.update)
-            return "editor";
-        return "viewer";
-    }
-    /**
-     * Normalizes permissions from SDS API format to SDK format.
-     *
-     * The SDS API returns permissions as an object with boolean flags
-     * (e.g., `{ read: true, create: true, update: false, ... }`).
-     * This method ensures all expected fields are present with default values.
-     *
-     * @param permissions - Permissions object from SDS API
-     * @returns Normalized permission flags object
-     * @internal
-     */
-    parsePermissions(permissions) {
-        return {
-            read: permissions.read ?? false,
-            create: permissions.create ?? false,
-            update: permissions.update ?? false,
-            delete: permissions.delete ?? false,
-            admin: permissions.admin ?? false,
-            owner: permissions.owner ?? false,
-        };
-    }
     /**
-     * Grants repository access to a user.
+     * Creates a new project that organizes multiple hypercert activities.
      *
-     * @param params - Grant parameters
-     * @param params.userDid - DID of the user to grant access to
-     * @param params.role - Role to assign (determines permissions)
-     * @throws {@link NetworkError} if the grant operation fails
+     * Projects are now implemented as collections with `type='project'`.
      *
-     * @remarks
-     * If the user already has access, their permissions are updated
-     * to the new role.
+     * @param params - Project creation parameters
+     * @returns Promise resolving to created project URI and CID
      *
      * @example
      * ```typescript
-     * // Grant viewer access
-     * await repo.collaborators.grant({
-     *   userDid: "did:plc:viewer-user",
-     *   role: "viewer",
-     * });
-     *
-     * // Upgrade to editor
-     * await repo.collaborators.grant({
-     *   userDid: "did:plc:viewer-user",
-     *   role: "editor",
+     * const result = await repo.hypercerts.createProject({
+     *   title: "Climate Impact 2024",
+     *   shortDescription: "Year-long climate initiative",
+     *   activities: [
+     *     { uri: activity1Uri, cid: activity1Cid, weight: "0.6" },
+     *     { uri: activity2Uri, cid: activity2Cid, weight: "0.4" }
+     *   ]
      * });
+     * console.log(`Created project: ${result.uri}`);
      * ```
      */
-    async grant(params) {
-        const permissions = this.roleToPermissions(params.role);
-        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.grantAccess`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
+    async createProject(params) {
+        try {
+            const createdAt = new Date().toISOString();
+            // Upload avatar blob if provided
+            let avatarRef;
+            if (params.avatar) {
+                const arrayBuffer = await params.avatar.arrayBuffer();
+                const uint8Array = new Uint8Array(arrayBuffer);
+                const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+                    encoding: params.avatar.type || "image/jpeg",
+                });
+                if (uploadResult.success) {
+                    avatarRef = {
+                        $type: "blob",
+                        ref: { $link: uploadResult.data.blob.ref.toString() },
+                        mimeType: uploadResult.data.blob.mimeType,
+                        size: uploadResult.data.blob.size,
+                    };
+                }
+                else {
+                    throw new NetworkError("Failed to upload avatar image");
+                }
+            }
+            // Upload banner blob if provided
+            let bannerRef;
+            if (params.banner) {
+                const arrayBuffer = await params.banner.arrayBuffer();
+                const uint8Array = new Uint8Array(arrayBuffer);
+                const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+                    encoding: params.banner.type || "image/jpeg",
+                });
+                if (uploadResult.success) {
+                    bannerRef = {
+                        $type: "blob",
+                        ref: { $link: uploadResult.data.blob.ref.toString() },
+                        mimeType: uploadResult.data.blob.mimeType,
+                        size: uploadResult.data.blob.size,
+                    };
+                }
+                else {
+                    throw new NetworkError("Failed to upload banner image");
+                }
+            }
+            // Build project record as a collection with type='project'
+            // Collections require 'items' array, so we map activities to items
+            const items = params.activities?.map((a) => ({
+                itemIdentifier: { uri: a.uri, cid: a.cid },
+                itemWeight: a.weight,
+            })) || [];
+            const projectRecord = {
+                $type: HYPERCERT_COLLECTIONS.COLLECTION,
+                type: "project",
+                title: params.title,
+                shortDescription: params.shortDescription,
+                items,
+                createdAt,
+            };
+            // Add optional fields
+            if (params.description) {
+                projectRecord.description = params.description;
+            }
+            if (avatarRef) {
+                projectRecord.avatar = avatarRef;
+            }
+            if (bannerRef) {
+                projectRecord.banner = bannerRef;
+            }
+            // Validate against collection lexicon
+            const validation = lexicon.validate(projectRecord, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid project record: ${validation.error?.message}`);
+            }
+            // Create record
+            const result = await this.agent.com.atproto.repo.createRecord({
                 repo: this.repoDid,
-                userDid: params.userDid,
-                permissions,
-            }),
-        });
-        if (!response.ok) {
-            throw new NetworkError(`Failed to grant access: ${response.statusText}`);
+                collection: HYPERCERT_COLLECTIONS.COLLECTION,
+                record: projectRecord,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to create project");
+            }
+            // Emit event
+            this.emit("projectCreated", { uri: result.data.uri, cid: result.data.cid });
+            return { uri: result.data.uri, cid: result.data.cid };
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to create project: ${error instanceof Error ? error.message : "Unknown"}`, error);
         }
     }
     /**
-     * Revokes repository access from a user.
+     * Gets a project by its AT-URI.
      *
-     * @param params - Revoke parameters
-     * @param params.userDid - DID of the user to revoke access from
-     * @throws {@link NetworkError} if the revoke operation fails
+     * Projects are collections with `type='project'`.
      *
-     * @remarks
-     * - Cannot revoke access from the repository owner
-     * - Revoked access is recorded with a `revokedAt` timestamp
+     * @param uri - AT-URI of the project
+     * @returns Promise resolving to project data (as collection)
      *
      * @example
      * ```typescript
-     * await repo.collaborators.revoke({
-     *   userDid: "did:plc:former-collaborator",
-     * });
+     * const { record } = await repo.hypercerts.getProject(projectUri);
+     * console.log(`${record.title}: ${record.items?.length || 0} activities`);
+     * ```
+     */
+    async getProject(uri) {
+        try {
+            // Parse URI
+            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+            if (!uriMatch) {
+                throw new ValidationError(`Invalid URI format: ${uri}`);
+            }
+            const [, , collection, rkey] = uriMatch;
+            // Fetch record
+            const result = await this.agent.com.atproto.repo.getRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to get project");
+            }
+            // Validate as collection
+            const validation = lexicon.validate(result.data.value, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid project record format: ${validation.error?.message}`);
+            }
+            // Verify it's actually a project (collection with type='project')
+            const record = result.data.value;
+            if (record.type !== "project") {
+                throw new ValidationError(`Record is not a project (type='${record.type}')`);
+            }
+            return {
+                uri: result.data.uri,
+                cid: result.data.cid ?? "",
+                record,
+            };
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to get project: ${error instanceof Error ? error.message : "Unknown"}`, error);
+        }
+    }
+    /**
+     * Lists all projects with optional pagination.
+     *
+     * Projects are collections with `type='project'`. This method filters
+     * collections to only return those with type='project'.
+     *
+     * @param params - Optional pagination parameters
+     * @returns Promise resolving to paginated list of projects
+     *
+     * @example
+     * ```typescript
+     * const { records } = await repo.hypercerts.listProjects();
+     * for (const { record } of records) {
+     *   console.log(`${record.title}: ${record.shortDescription}`);
+     * }
+     * ```
+     */
+    async listProjects(params) {
+        try {
+            const limit = params?.limit;
+            let cursor = params?.cursor;
+            const allRecords = [];
+            // Loop-fetch until we have enough projects or no more cursor
+            while (!cursor || allRecords.length < (limit ?? Infinity)) {
+                const result = await this.agent.com.atproto.repo.listRecords({
+                    repo: this.repoDid,
+                    collection: HYPERCERT_COLLECTIONS.COLLECTION,
+                    limit: limit ?? 50,
+                    cursor,
+                });
+                if (!result.success) {
+                    throw new NetworkError("Failed to list projects");
+                }
+                // Filter and collect project records
+                for (const r of result.data.records ?? []) {
+                    const record = r.value;
+                    if (record.type === "project") {
+                        allRecords.push({ uri: r.uri, cid: r.cid, record });
+                    }
+                    // Stop if we've collected enough
+                    if (limit && allRecords.length >= limit)
+                        break;
+                }
+                // Update cursor; break if no more pages
+                cursor = result.data.cursor;
+                if (!cursor)
+                    break;
+            }
+            return { records: allRecords, cursor };
+        }
+        catch (error) {
+            if (error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to list projects: ${error instanceof Error ? error.message : "Unknown"}`, error);
+        }
+    }
+    /**
+     * Updates an existing project.
+     *
+     * Projects are collections with `type='project'`.
+     *
+     * @param uri - AT-URI of the project to update
+     * @param updates - Fields to update
+     * @returns Promise resolving to updated project URI and CID
+     *
+     * @example
+     * ```typescript
+     * const result = await repo.hypercerts.updateProject(projectUri, {
+     *   title: "Updated Project Title",
+     *   shortDescription: "New description"
+     * });
+     * ```
+     */
+    async updateProject(uri, updates) {
+        try {
+            // Parse URI and fetch existing record
+            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+            if (!uriMatch) {
+                throw new ValidationError(`Invalid URI format: ${uri}`);
+            }
+            const [, , collection, rkey] = uriMatch;
+            const existing = await this.agent.com.atproto.repo.getRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+            });
+            if (!existing.success) {
+                throw new NetworkError(`Project not found: ${uri}`);
+            }
+            const existingRecord = existing.data.value;
+            // Verify it's actually a project
+            if (existingRecord.type !== "project") {
+                throw new ValidationError(`Record is not a project (type='${existingRecord.type}')`);
+            }
+            // Merge updates with existing record
+            const recordForUpdate = {
+                ...existingRecord,
+                // MUST preserve type, createdAt, and items structure
+                type: "project",
+                createdAt: existingRecord.createdAt,
+            };
+            // Apply simple field updates
+            if (updates.title !== undefined)
+                recordForUpdate.title = updates.title;
+            if (updates.shortDescription !== undefined)
+                recordForUpdate.shortDescription = updates.shortDescription;
+            if (updates.description !== undefined)
+                recordForUpdate.description = updates.description;
+            // Handle avatar update with three-way logic
+            delete recordForUpdate.avatar;
+            if (updates.avatar !== undefined) {
+                if (updates.avatar === null) {
+                    // Remove avatar
+                }
+                else {
+                    const arrayBuffer = await updates.avatar.arrayBuffer();
+                    const uint8Array = new Uint8Array(arrayBuffer);
+                    const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+                        encoding: updates.avatar.type || "image/jpeg",
+                    });
+                    if (uploadResult.success) {
+                        recordForUpdate.avatar = {
+                            $type: "blob",
+                            ref: uploadResult.data.blob.ref,
+                            mimeType: uploadResult.data.blob.mimeType,
+                            size: uploadResult.data.blob.size,
+                        };
+                    }
+                    else {
+                        throw new NetworkError("Failed to upload avatar image");
+                    }
+                }
+            }
+            else if (existingRecord.avatar) {
+                recordForUpdate.avatar = existingRecord.avatar;
+            }
+            // Handle banner update
+            delete recordForUpdate.banner;
+            if (updates.banner !== undefined) {
+                if (updates.banner === null) {
+                    // Remove banner
+                }
+                else {
+                    const arrayBuffer = await updates.banner.arrayBuffer();
+                    const uint8Array = new Uint8Array(arrayBuffer);
+                    const uploadResult = await this.agent.com.atproto.repo.uploadBlob(uint8Array, {
+                        encoding: updates.banner.type || "image/jpeg",
+                    });
+                    if (uploadResult.success) {
+                        recordForUpdate.banner = {
+                            $type: "blob",
+                            ref: uploadResult.data.blob.ref,
+                            mimeType: uploadResult.data.blob.mimeType,
+                            size: uploadResult.data.blob.size,
+                        };
+                    }
+                    else {
+                        throw new NetworkError("Failed to upload banner image");
+                    }
+                }
+            }
+            else if (existingRecord.banner) {
+                recordForUpdate.banner = existingRecord.banner;
+            }
+            // Transform activities to items array
+            if (updates.activities) {
+                recordForUpdate.items = updates.activities.map((a) => ({
+                    itemIdentifier: { uri: a.uri, cid: a.cid },
+                    itemWeight: a.weight,
+                }));
+            }
+            else {
+                // Preserve existing items
+                recordForUpdate.items = existingRecord.items;
+            }
+            // Validate merged record
+            const validation = lexicon.validate(recordForUpdate, HYPERCERT_COLLECTIONS.COLLECTION, "main", false);
+            if (!validation.success) {
+                throw new ValidationError(`Invalid project record: ${validation.error?.message}`);
+            }
+            // Update record
+            const result = await this.agent.com.atproto.repo.putRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+                record: recordForUpdate,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to update project");
+            }
+            // Emit event
+            this.emit("projectUpdated", { uri: result.data.uri, cid: result.data.cid });
+            return { uri: result.data.uri, cid: result.data.cid };
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to update project: ${error instanceof Error ? error.message : "Unknown"}`, error);
+        }
+    }
+    /**
+     * Deletes a project.
+     *
+     * Projects are collections with `type='project'`.
+     *
+     * @param uri - AT-URI of the project to delete
+     *
+     * @example
+     * ```typescript
+     * await repo.hypercerts.deleteProject(projectUri);
+     * console.log("Project deleted");
+     * ```
+     */
+    async deleteProject(uri) {
+        try {
+            // Parse URI
+            const uriMatch = uri.match(/^at:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+            if (!uriMatch) {
+                throw new ValidationError(`Invalid URI format: ${uri}`);
+            }
+            const [, , collection, rkey] = uriMatch;
+            // Verify it's actually a project before deleting
+            const existing = await this.agent.com.atproto.repo.getRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+            });
+            if (existing.success) {
+                const record = existing.data.value;
+                if (record.type !== "project") {
+                    throw new ValidationError(`Record is not a project (type='${record.type}')`);
+                }
+            }
+            // Delete record
+            const result = await this.agent.com.atproto.repo.deleteRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to delete project");
+            }
+            // Emit event
+            this.emit("projectDeleted", { uri });
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError)
+                throw error;
+            throw new NetworkError(`Failed to delete project: ${error instanceof Error ? error.message : "Unknown"}`, error);
+        }
+    }
+}
+
+/**
+ * CollaboratorOperationsImpl - SDS collaborator management operations.
+ *
+ * This module provides the implementation for managing collaborator
+ * access on Shared Data Server (SDS) repositories.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Implementation of collaborator operations for SDS access control.
+ *
+ * This class manages access permissions for shared repositories on
+ * Shared Data Servers (SDS). It provides role-based access control
+ * with predefined permission sets.
+ *
+ * @remarks
+ * This class is typically not instantiated directly. Access it through
+ * {@link Repository.collaborators} on an SDS-connected repository.
+ *
+ * **Role Hierarchy**:
+ * - `viewer`: Read-only access
+ * - `editor`: Read + Create + Update
+ * - `admin`: All permissions except ownership transfer
+ * - `owner`: Full control including ownership management
+ *
+ * **SDS API Endpoints Used**:
+ * - `com.sds.repo.grantAccess`: Grant access to a user
+ * - `com.sds.repo.revokeAccess`: Revoke access from a user
+ * - `com.sds.repo.listCollaborators`: List all collaborators
+ * - `com.sds.repo.getPermissions`: Get current user's permissions
+ * - `com.sds.repo.transferOwnership`: Transfer repository ownership
+ *
+ * @example
+ * ```typescript
+ * // Get SDS repository
+ * const sdsRepo = sdk.repository(session, { server: "sds" });
+ *
+ * // Grant editor access
+ * await sdsRepo.collaborators.grant({
+ *   userDid: "did:plc:new-user",
+ *   role: "editor",
+ * });
+ *
+ * // List all collaborators
+ * const collaborators = await sdsRepo.collaborators.list();
+ *
+ * // Check specific user
+ * const hasAccess = await sdsRepo.collaborators.hasAccess("did:plc:someone");
+ * const role = await sdsRepo.collaborators.getRole("did:plc:someone");
+ * ```
+ *
+ * @internal
+ */
+class CollaboratorOperationsImpl {
+    /**
+     * Creates a new CollaboratorOperationsImpl.
+     *
+     * @param session - Authenticated OAuth session with fetchHandler
+     * @param repoDid - DID of the repository to manage
+     * @param serverUrl - SDS server URL
+     *
+     * @internal
+     */
+    constructor(session, repoDid, serverUrl) {
+        this.session = session;
+        this.repoDid = repoDid;
+        this.serverUrl = serverUrl;
+    }
+    /**
+     * Converts a role to its corresponding permissions object.
+     *
+     * @param role - The role to convert
+     * @returns Permission flags for the role
+     * @internal
+     */
+    roleToPermissions(role) {
+        switch (role) {
+            case "viewer":
+                return { read: true, create: false, update: false, delete: false, admin: false, owner: false };
+            case "editor":
+                return { read: true, create: true, update: true, delete: false, admin: false, owner: false };
+            case "admin":
+                return { read: true, create: true, update: true, delete: true, admin: true, owner: false };
+            case "owner":
+                return { read: true, create: true, update: true, delete: true, admin: true, owner: true };
+        }
+    }
+    /**
+     * Determines the role from a permissions object.
+     *
+     * @param permissions - The permissions to analyze
+     * @returns The highest role matching the permissions
+     * @internal
+     */
+    permissionsToRole(permissions) {
+        if (permissions.owner)
+            return "owner";
+        if (permissions.admin)
+            return "admin";
+        if (permissions.create || permissions.update)
+            return "editor";
+        return "viewer";
+    }
+    /**
+     * Normalizes permissions from SDS API format to SDK format.
+     *
+     * The SDS API returns permissions as an object with boolean flags
+     * (e.g., `{ read: true, create: true, update: false, ... }`).
+     * This method ensures all expected fields are present with default values.
+     *
+     * @param permissions - Permissions object from SDS API
+     * @returns Normalized permission flags object
+     * @internal
+     */
+    parsePermissions(permissions) {
+        return {
+            read: permissions.read ?? false,
+            create: permissions.create ?? false,
+            update: permissions.update ?? false,
+            delete: permissions.delete ?? false,
+            admin: permissions.admin ?? false,
+            owner: permissions.owner ?? false,
+        };
+    }
+    /**
+     * Grants repository access to a user.
+     *
+     * @param params - Grant parameters
+     * @param params.userDid - DID of the user to grant access to
+     * @param params.role - Role to assign (determines permissions)
+     * @throws {@link NetworkError} if the grant operation fails
+     *
+     * @remarks
+     * If the user already has access, their permissions are updated
+     * to the new role.
+     *
+     * @example
+     * ```typescript
+     * // Grant viewer access
+     * await repo.collaborators.grant({
+     *   userDid: "did:plc:viewer-user",
+     *   role: "viewer",
+     * });
+     *
+     * // Upgrade to editor
+     * await repo.collaborators.grant({
+     *   userDid: "did:plc:viewer-user",
+     *   role: "editor",
+     * });
+     * ```
+     */
+    async grant(params) {
+        const permissions = this.roleToPermissions(params.role);
+        const response = await this.session.fetchHandler(`${this.serverUrl}/xrpc/com.sds.repo.grantAccess`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                repo: this.repoDid,
+                userDid: params.userDid,
+                permissions,
+            }),
+        });
+        if (!response.ok) {
+            throw new NetworkError(`Failed to grant access: ${response.statusText}`);
+        }
+    }
+    /**
+     * Revokes repository access from a user.
+     *
+     * @param params - Revoke parameters
+     * @param params.userDid - DID of the user to revoke access from
+     * @throws {@link NetworkError} if the revoke operation fails
+     *
+     * @remarks
+     * - Cannot revoke access from the repository owner
+     * - Revoked access is recorded with a `revokedAt` timestamp
+     *
+     * @example
+     * ```typescript
+     * await repo.collaborators.revoke({
+     *   userDid: "did:plc:former-collaborator",
+     * });
      * ```
      */
     async revoke(params) {
@@ -4833,6 +5833,7 @@ class Repository {
      * @param repoDid - DID of the repository to operate on
      * @param isSDS - Whether this is a Shared Data Server
      * @param logger - Optional logger for debugging
+     * @param lexiconRegistry - Registry for custom lexicon management
      *
      * @remarks
      * This constructor is typically not called directly. Use
@@ -4840,12 +5841,13 @@ class Repository {
      *
      * @internal
      */
-    constructor(session, serverUrl, repoDid, isSDS, logger) {
+    constructor(session, serverUrl, repoDid, isSDS, logger, lexiconRegistry) {
         this.session = session;
         this.serverUrl = serverUrl;
         this.repoDid = repoDid;
         this._isSDS = isSDS;
         this.logger = logger;
+        this.lexiconRegistry = lexiconRegistry || new LexiconRegistry();
         // Create a ConfigurableAgent that routes requests to the specified server URL
         // This allows routing to PDS, SDS, or any custom server while maintaining
         // the OAuth session's authentication
@@ -4920,7 +5922,53 @@ class Repository {
      * ```
      */
     repo(did) {
-        return new Repository(this.session, this.serverUrl, did, this._isSDS, this.logger);
+        return new Repository(this.session, this.serverUrl, did, this._isSDS, this.logger, this.lexiconRegistry);
+    }
+    /**
+     * Gets the LexiconRegistry instance for managing custom lexicons.
+     *
+     * The registry is shared across all operations in this repository and
+     * enables validation of custom record types.
+     *
+     * @returns The {@link LexiconRegistry} instance
+     *
+     * @example
+     * ```typescript
+     * // Access the registry
+     * const registry = repo.getLexiconRegistry();
+     *
+     * // Register a custom lexicon
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.evaluation",
+     *   defs: {
+     *     main: {
+     *       type: "record",
+     *       key: "tid",
+     *       record: {
+     *         type: "object",
+     *         required: ["$type", "score"],
+     *         properties: {
+     *           "$type": { type: "string", const: "org.myapp.evaluation" },
+     *           score: { type: "integer", minimum: 0, maximum: 100 }
+     *         }
+     *       }
+     *     }
+     *   }
+     * });
+     *
+     * // Now create records using the custom lexicon
+     * await repo.records.create({
+     *   collection: "org.myapp.evaluation",
+     *   record: {
+     *     $type: "org.myapp.evaluation",
+     *     score: 85
+     *   }
+     * });
+     * ```
+     */
+    getLexiconRegistry() {
+        return this.lexiconRegistry;
     }
     /**
      * Low-level record operations for CRUD on any AT Protocol record type.
@@ -4953,7 +6001,7 @@ class Repository {
      */
     get records() {
         if (!this._records) {
-            this._records = new RecordOperationsImpl(this.agent, this.repoDid);
+            this._records = new RecordOperationsImpl(this.agent, this.repoDid, this.lexiconRegistry);
         }
         return this._records;
     }
@@ -5130,26 +6178,67 @@ class Repository {
     }
 }
 
+/**
+ * Custom URL validator that allows HTTP loopback addresses for development.
+ *
+ * Accepts:
+ * - Any HTTPS URL (production)
+ * - http://localhost (with optional port and path)
+ * - http://127.0.0.1 (with optional port and path)
+ * - http://[::1] (with optional port and path) - IPv6 loopback
+ *
+ * Rejects:
+ * - Other HTTP URLs (e.g., http://example.com)
+ * - Invalid URLs
+ *
+ * @internal
+ */
+const urlOrLoopback = zod.z.string().refine((value) => {
+    try {
+        const url = new URL(value);
+        // Always allow HTTPS
+        if (url.protocol === "https:") {
+            return true;
+        }
+        // For HTTP, only allow loopback addresses
+        if (url.protocol === "http:") {
+            const hostname = url.hostname.toLowerCase();
+            return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}, {
+    message: "Must be a valid HTTPS URL or HTTP loopback URL (localhost, 127.0.0.1, [::1])",
+});
 /**
  * Zod schema for OAuth configuration validation.
  *
  * @remarks
- * All URLs must be valid and use HTTPS in production. The `jwkPrivate` field
- * should contain the private key in JWK (JSON Web Key) format as a string.
+ * All URLs must be valid and use HTTPS in production. For local development,
+ * HTTP loopback URLs (localhost, 127.0.0.1, [::1]) are allowed.
+ * The `jwkPrivate` field should contain the private key in JWK (JSON Web Key) format as a string.
  */
 const OAuthConfigSchema = zod.z.object({
     /**
      * URL to the OAuth client metadata JSON document.
      * This document describes your application to the authorization server.
      *
+     * For local development, you can use `http://localhost/` as a loopback client.
+     *
      * @see https://atproto.com/specs/oauth#client-metadata
      */
-    clientId: zod.z.string().url(),
+    clientId: urlOrLoopback,
     /**
      * URL where users are redirected after authentication.
      * Must match one of the redirect URIs in your client metadata.
+     *
+     * For local development, you can use HTTP loopback URLs like
+     * `http://127.0.0.1:3000/callback` or `http://localhost:3000/callback`.
      */
-    redirectUri: zod.z.string().url(),
+    redirectUri: urlOrLoopback,
     /**
      * OAuth scopes to request, space-separated.
      *
@@ -5183,8 +6272,11 @@ const OAuthConfigSchema = zod.z.object({
     /**
      * URL to your public JWKS (JSON Web Key Set) endpoint.
      * Used by the authorization server to verify your client's signatures.
+     *
+     * For local development, you can serve JWKS from a loopback URL like
+     * `http://127.0.0.1:3000/.well-known/jwks.json`.
      */
-    jwksUri: zod.z.string().url(),
+    jwksUri: urlOrLoopback,
     /**
      * Private JWK (JSON Web Key) as a JSON string.
      * Used for signing DPoP proofs and client assertions.
@@ -5194,28 +6286,64 @@ const OAuthConfigSchema = zod.z.object({
      * Typically loaded from environment variables or a secrets manager.
      */
     jwkPrivate: zod.z.string(),
+    /**
+     * Enable development mode features (optional).
+     *
+     * When true, suppresses warnings about using HTTP loopback URLs.
+     * Should be set to true for local development to reduce console noise.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * oauth: {
+     *   clientId: "http://localhost/",
+     *   redirectUri: "http://127.0.0.1:3000/callback",
+     *   // ... other config
+     *   developmentMode: true, // Suppress loopback warnings
+     * }
+     * ```
+     */
+    developmentMode: zod.z.boolean().optional(),
 });
 /**
  * Zod schema for server URL configuration.
  *
  * @remarks
  * At least one server (PDS or SDS) should be configured for the SDK to be useful.
+ * For local development, HTTP loopback URLs are allowed.
  */
 const ServerConfigSchema = zod.z.object({
     /**
      * Personal Data Server URL - the user's own AT Protocol server.
      * This is the primary server for user data operations.
      *
-     * @example "https://bsky.social"
+     * @example Production
+     * ```typescript
+     * pds: "https://bsky.social"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * pds: "http://localhost:2583"
+     * ```
      */
-    pds: zod.z.string().url().optional(),
+    pds: urlOrLoopback.optional(),
     /**
      * Shared Data Server URL - for collaborative data storage.
      * Required for collaborator and organization operations.
      *
-     * @example "https://sds.hypercerts.org"
+     * @example Production
+     * ```typescript
+     * sds: "https://sds.hypercerts.org"
+     * ```
+     *
+     * @example Local development
+     * ```typescript
+     * sds: "http://127.0.0.1:2584"
+     * ```
      */
-    sds: zod.z.string().url().optional(),
+    sds: urlOrLoopback.optional(),
 });
 /**
  * Zod schema for timeout configuration.
@@ -5342,6 +6470,10 @@ class ATProtoSDK {
         };
         this.config = configWithDefaults;
         this.logger = config.logger;
+        // Initialize lexicon registry with hypercert lexicons
+        // Filter out undefined lexicons (some may not be exported from lexicon package yet)
+        const validLexicons = HYPERCERT_LEXICONS.filter((lex) => lex !== undefined);
+        this.lexiconRegistry = new LexiconRegistry(validLexicons);
         // Initialize OAuth client
         this.oauthClient = new OAuthClient(configWithDefaults);
         this.logger?.info("ATProto SDK initialized");
@@ -5625,45 +6757,1160 @@ class ATProtoSDK {
         }
         // Get repository DID (default to session DID)
         const repoDid = session.did || session.sub;
-        return new Repository(session, serverUrl, repoDid, isSDS, this.logger);
+        return new Repository(session, serverUrl, repoDid, isSDS, this.logger, this.lexiconRegistry);
+    }
+    /**
+     * Gets the LexiconRegistry instance for managing custom lexicons.
+     *
+     * The registry allows you to register custom lexicon schemas and validate
+     * records against them. All registered lexicons will be automatically
+     * validated during record creation operations.
+     *
+     * @returns The {@link LexiconRegistry} instance
+     *
+     * @example
+     * ```typescript
+     * // Register a custom lexicon
+     * const registry = sdk.getLexiconRegistry();
+     * registry.register({
+     *   lexicon: 1,
+     *   id: "org.myapp.customRecord",
+     *   defs: { ... }
+     * });
+     *
+     * // Check if lexicon is registered
+     * if (registry.isRegistered("org.myapp.customRecord")) {
+     *   console.log("Custom lexicon is available");
+     * }
+     * ```
+     */
+    getLexiconRegistry() {
+        return this.lexiconRegistry;
+    }
+    /**
+     * The configured PDS (Personal Data Server) URL.
+     *
+     * @returns The PDS URL if configured, otherwise `undefined`
+     */
+    get pdsUrl() {
+        return this.config.servers?.pds;
+    }
+    /**
+     * The configured SDS (Shared Data Server) URL.
+     *
+     * @returns The SDS URL if configured, otherwise `undefined`
+     */
+    get sdsUrl() {
+        return this.config.servers?.sds;
+    }
+}
+/**
+ * Factory function to create an ATProto SDK instance.
+ *
+ * This is a convenience function equivalent to `new ATProtoSDK(config)`.
+ *
+ * @param config - SDK configuration
+ * @returns A new {@link ATProtoSDK} instance
+ *
+ * @example
+ * ```typescript
+ * import { createATProtoSDK } from "@hypercerts-org/sdk";
+ *
+ * const sdk = createATProtoSDK({
+ *   oauth: { ... },
+ *   servers: { pds: "https://bsky.social" },
+ * });
+ * ```
+ */
+function createATProtoSDK(config) {
+    return new ATProtoSDK(config);
+}
+
+/**
+ * BaseOperations - Abstract base class for custom lexicon operations.
+ *
+ * This module provides a foundation for building domain-specific operation
+ * classes that work with custom lexicons. It handles validation, record
+ * creation, and provides utilities for working with AT Protocol records.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Abstract base class for creating custom lexicon operation classes.
+ *
+ * Extend this class to build domain-specific operations for your custom
+ * lexicons. The base class provides:
+ *
+ * - Automatic validation against registered lexicon schemas
+ * - Helper methods for creating and updating records
+ * - Utilities for building strongRefs and AT-URIs
+ * - Error handling and logging support
+ *
+ * @typeParam TParams - Type of parameters accepted by the create() method
+ * @typeParam TResult - Type of result returned by the create() method
+ *
+ * @remarks
+ * This class is designed to be extended by developers creating custom
+ * operation classes for their own lexicons. It follows the same patterns
+ * as the built-in hypercert operations.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { BaseOperations } from "@hypercerts-org/sdk-core";
+ *
+ * interface EvaluationParams {
+ *   subjectUri: string;
+ *   subjectCid: string;
+ *   score: number;
+ *   methodology?: string;
+ * }
+ *
+ * interface EvaluationResult {
+ *   uri: string;
+ *   cid: string;
+ *   record: MyEvaluation;
+ * }
+ *
+ * class EvaluationOperations extends BaseOperations<EvaluationParams, EvaluationResult> {
+ *   async create(params: EvaluationParams): Promise<EvaluationResult> {
+ *     const record = {
+ *       $type: "org.myapp.evaluation",
+ *       subject: this.createStrongRef(params.subjectUri, params.subjectCid),
+ *       score: params.score,
+ *       methodology: params.methodology,
+ *       createdAt: new Date().toISOString(),
+ *     };
+ *
+ *     const { uri, cid } = await this.validateAndCreate("org.myapp.evaluation", record);
+ *     return { uri, cid, record };
+ *   }
+ * }
+ * ```
+ *
+ * @example With validation and error handling
+ * ```typescript
+ * class ProjectOperations extends BaseOperations<CreateProjectParams, ProjectResult> {
+ *   async create(params: CreateProjectParams): Promise<ProjectResult> {
+ *     // Validate input parameters
+ *     if (!params.title || params.title.trim().length === 0) {
+ *       throw new ValidationError("Project title cannot be empty");
+ *     }
+ *
+ *     const record = {
+ *       $type: "org.myapp.project",
+ *       title: params.title,
+ *       description: params.description,
+ *       createdAt: new Date().toISOString(),
+ *     };
+ *
+ *     try {
+ *       const { uri, cid } = await this.validateAndCreate("org.myapp.project", record);
+ *       this.logger?.info(`Created project: ${uri}`);
+ *       return { uri, cid, record };
+ *     } catch (error) {
+ *       this.logger?.error(`Failed to create project: ${error}`);
+ *       throw error;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class BaseOperations {
+    /**
+     * Creates a new BaseOperations instance.
+     *
+     * @param agent - AT Protocol Agent for making API calls
+     * @param repoDid - DID of the repository to operate on
+     * @param lexiconRegistry - Registry for validating records against lexicon schemas
+     * @param logger - Optional logger for debugging and monitoring
+     *
+     * @internal
+     */
+    constructor(agent, repoDid, lexiconRegistry, logger) {
+        this.agent = agent;
+        this.repoDid = repoDid;
+        this.lexiconRegistry = lexiconRegistry;
+        this.logger = logger;
+    }
+    /**
+     * Validates a record against its lexicon schema and creates it in the repository.
+     *
+     * This method performs the following steps:
+     * 1. Validates the record against the registered lexicon schema
+     * 2. Throws ValidationError if validation fails
+     * 3. Creates the record using the AT Protocol Agent
+     * 4. Returns the created record's URI and CID
+     *
+     * @param collection - NSID of the collection (e.g., "org.myapp.customRecord")
+     * @param record - Record data conforming to the collection's lexicon schema
+     * @param rkey - Optional record key. If not provided, a TID is auto-generated
+     * @returns Promise resolving to the created record's URI and CID
+     * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @example
+     * ```typescript
+     * const record = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: { uri: "at://...", cid: "bafyrei..." },
+     *   score: 85,
+     *   createdAt: new Date().toISOString(),
+     * };
+     *
+     * const { uri, cid } = await this.validateAndCreate("org.myapp.evaluation", record);
+     * ```
+     */
+    async validateAndCreate(collection, record, rkey) {
+        // Validate record against registered lexicon
+        if (this.lexiconRegistry.isRegistered(collection)) {
+            const validation = this.lexiconRegistry.validate(collection, record);
+            if (!validation.valid) {
+                throw new ValidationError(`Invalid ${collection}: ${validation.error}`);
+            }
+        }
+        try {
+            const result = await this.agent.com.atproto.repo.createRecord({
+                repo: this.repoDid,
+                collection,
+                record: record,
+                rkey,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to create record");
+            }
+            return { uri: result.data.uri, cid: result.data.cid };
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError) {
+                throw error;
+            }
+            throw new NetworkError(`Failed to create ${collection}: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        }
+    }
+    /**
+     * Validates a record against its lexicon schema and updates it in the repository.
+     *
+     * This method performs the following steps:
+     * 1. Validates the record against the registered lexicon schema
+     * 2. Throws ValidationError if validation fails
+     * 3. Updates the record using the AT Protocol Agent
+     * 4. Returns the updated record's URI and new CID
+     *
+     * @param collection - NSID of the collection
+     * @param rkey - Record key (the last segment of the AT-URI)
+     * @param record - New record data (completely replaces existing record)
+     * @returns Promise resolving to the updated record's URI and new CID
+     * @throws {@link ValidationError} if the record doesn't conform to the lexicon schema
+     * @throws {@link NetworkError} if the API request fails
+     *
+     * @remarks
+     * This is a full replacement operation, not a partial update.
+     *
+     * @example
+     * ```typescript
+     * const updatedRecord = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: { uri: "at://...", cid: "bafyrei..." },
+     *   score: 90, // Updated score
+     *   createdAt: existingRecord.createdAt,
+     * };
+     *
+     * const { uri, cid } = await this.validateAndUpdate(
+     *   "org.myapp.evaluation",
+     *   "abc123",
+     *   updatedRecord
+     * );
+     * ```
+     */
+    async validateAndUpdate(collection, rkey, record) {
+        // Validate record against registered lexicon
+        if (this.lexiconRegistry.isRegistered(collection)) {
+            const validation = this.lexiconRegistry.validate(collection, record);
+            if (!validation.valid) {
+                throw new ValidationError(`Invalid ${collection}: ${validation.error}`);
+            }
+        }
+        try {
+            const result = await this.agent.com.atproto.repo.putRecord({
+                repo: this.repoDid,
+                collection,
+                rkey,
+                record: record,
+            });
+            if (!result.success) {
+                throw new NetworkError("Failed to update record");
+            }
+            return { uri: result.data.uri, cid: result.data.cid };
+        }
+        catch (error) {
+            if (error instanceof ValidationError || error instanceof NetworkError) {
+                throw error;
+            }
+            throw new NetworkError(`Failed to update ${collection}: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+        }
+    }
+    /**
+     * Creates a strongRef object from a URI and CID.
+     *
+     * StrongRefs are used in AT Protocol to reference specific versions
+     * of records. They ensure that references point to an exact record
+     * version, not just the latest version.
+     *
+     * @param uri - AT-URI of the record (e.g., "at://did:plc:abc/collection/rkey")
+     * @param cid - Content Identifier (CID) of the record
+     * @returns StrongRef object with uri and cid properties
+     *
+     * @example
+     * ```typescript
+     * const hypercertRef = this.createStrongRef(
+     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789",
+     *   "bafyreiabc123..."
+     * );
+     *
+     * const evaluation = {
+     *   $type: "org.myapp.evaluation",
+     *   subject: hypercertRef, // Reference to specific hypercert version
+     *   score: 85,
+     *   createdAt: new Date().toISOString(),
+     * };
+     * ```
+     */
+    createStrongRef(uri, cid) {
+        return { uri, cid };
+    }
+    /**
+     * Creates a strongRef from a CreateResult or UpdateResult.
+     *
+     * This is a convenience method for creating strongRefs from the
+     * results of create or update operations.
+     *
+     * @param result - Result from a create or update operation
+     * @returns StrongRef object with uri and cid properties
+     *
+     * @example
+     * ```typescript
+     * // Create a project
+     * const projectResult = await this.validateAndCreate("org.myapp.project", projectRecord);
+     *
+     * // Create a task that references the project
+     * const taskRecord = {
+     *   $type: "org.myapp.task",
+     *   project: this.createStrongRefFromResult(projectResult),
+     *   title: "Implement feature",
+     *   createdAt: new Date().toISOString(),
+     * };
+     * ```
+     */
+    createStrongRefFromResult(result) {
+        return { uri: result.uri, cid: result.cid };
+    }
+    /**
+     * Parses an AT-URI to extract its components.
+     *
+     * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+     *
+     * @param uri - AT-URI to parse
+     * @returns Object containing did, collection, and rkey
+     * @throws Error if the URI format is invalid
+     *
+     * @example
+     * ```typescript
+     * const { did, collection, rkey } = this.parseAtUri(
+     *   "at://did:plc:abc123/org.hypercerts.claim.activity/xyz789"
+     * );
+     * // did: "did:plc:abc123"
+     * // collection: "org.hypercerts.claim.activity"
+     * // rkey: "xyz789"
+     * ```
+     */
+    parseAtUri(uri) {
+        if (!uri.startsWith("at://")) {
+            throw new Error(`Invalid AT-URI format: ${uri}`);
+        }
+        const parts = uri.slice(5).split("/"); // Remove "at://" and split
+        if (parts.length !== 3) {
+            throw new Error(`Invalid AT-URI format: ${uri}`);
+        }
+        return {
+            did: parts[0],
+            collection: parts[1],
+            rkey: parts[2],
+        };
+    }
+    /**
+     * Builds an AT-URI from its components.
+     *
+     * @param did - DID of the repository
+     * @param collection - NSID of the collection
+     * @param rkey - Record key (typically a TID)
+     * @returns Complete AT-URI string
+     *
+     * @example
+     * ```typescript
+     * const uri = this.buildAtUri(
+     *   "did:plc:abc123",
+     *   "org.myapp.evaluation",
+     *   "xyz789"
+     * );
+     * // Returns: "at://did:plc:abc123/org.myapp.evaluation/xyz789"
+     * ```
+     */
+    buildAtUri(did, collection, rkey) {
+        return `at://${did}/${collection}/${rkey}`;
+    }
+}
+
+/**
+ * Lexicon Development Utilities - AT-URI and StrongRef Helpers
+ *
+ * This module provides utilities for working with AT Protocol URIs and strongRefs
+ * when building custom lexicons. These tools help developers create type-safe
+ * references between records.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Parse an AT-URI into its component parts.
+ *
+ * Extracts the DID, collection NSID, and record key from an AT-URI string.
+ * AT-URIs follow the format: `at://{did}/{collection}/{rkey}`
+ *
+ * @param uri - The AT-URI to parse
+ * @returns The components of the URI
+ * @throws {Error} If the URI format is invalid
+ *
+ * @example
+ * ```typescript
+ * const components = parseAtUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(components);
+ * // {
+ * //   did: "did:plc:abc123",
+ * //   collection: "org.hypercerts.claim.activity",
+ * //   rkey: "3km2vj4kfqp2a"
+ * // }
+ * ```
+ */
+function parseAtUri(uri) {
+    if (!uri.startsWith("at://")) {
+        throw new Error(`Invalid AT-URI format: must start with "at://", got "${uri}"`);
+    }
+    const withoutProtocol = uri.slice(5); // Remove "at://"
+    const parts = withoutProtocol.split("/");
+    if (parts.length !== 3) {
+        throw new Error(`Invalid AT-URI format: expected "at://{did}/{collection}/{rkey}", got "${uri}"`);
+    }
+    const [did, collection, rkey] = parts;
+    if (!did || !collection || !rkey) {
+        throw new Error(`Invalid AT-URI format: all components must be non-empty, got "${uri}"`);
+    }
+    return { did, collection, rkey };
+}
+/**
+ * Build an AT-URI from its component parts.
+ *
+ * Constructs a valid AT-URI string from a DID, collection NSID, and record key.
+ * The resulting URI follows the format: `at://{did}/{collection}/{rkey}`
+ *
+ * @param did - The repository owner's DID
+ * @param collection - The collection NSID (lexicon identifier)
+ * @param rkey - The record key (TID or custom string)
+ * @returns The complete AT-URI
+ *
+ * @example
+ * ```typescript
+ * const uri = buildAtUri(
+ *   "did:plc:abc123",
+ *   "org.hypercerts.claim.activity",
+ *   "3km2vj4kfqp2a"
+ * );
+ * console.log(uri); // "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a"
+ * ```
+ */
+function buildAtUri(did, collection, rkey) {
+    if (!did || !collection || !rkey) {
+        throw new Error("All AT-URI components (did, collection, rkey) must be non-empty");
+    }
+    return `at://${did}/${collection}/${rkey}`;
+}
+/**
+ * Extract the record key (TID or custom key) from an AT-URI.
+ *
+ * Returns the last component of the AT-URI, which is the record key.
+ * This is equivalent to `parseAtUri(uri).rkey` but more efficient.
+ *
+ * @param uri - The AT-URI to extract from
+ * @returns The record key (TID or custom string)
+ * @throws {Error} If the URI format is invalid
+ *
+ * @example
+ * ```typescript
+ * const rkey = extractRkeyFromUri("at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a");
+ * console.log(rkey); // "3km2vj4kfqp2a"
+ * ```
+ */
+function extractRkeyFromUri(uri) {
+    const { rkey } = parseAtUri(uri);
+    return rkey;
+}
+/**
+ * Check if a string is a valid AT-URI format.
+ *
+ * Validates that the string follows the AT-URI format without throwing errors.
+ * This is useful for input validation before parsing.
+ *
+ * @param uri - The string to validate
+ * @returns True if the string is a valid AT-URI, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isValidAtUri(userInput)) {
+ *   const components = parseAtUri(userInput);
+ *   // ... use components
+ * } else {
+ *   console.error("Invalid AT-URI");
+ * }
+ * ```
+ */
+function isValidAtUri(uri) {
+    try {
+        parseAtUri(uri);
+        return true;
+    }
+    catch {
+        return false;
     }
-    /**
-     * The configured PDS (Personal Data Server) URL.
-     *
-     * @returns The PDS URL if configured, otherwise `undefined`
-     */
-    get pdsUrl() {
-        return this.config.servers?.pds;
+}
+/**
+ * Create a strongRef from a URI and CID.
+ *
+ * StrongRefs are the canonical way to reference specific versions of records
+ * in AT Protocol. They combine an AT-URI (which identifies the record) with
+ * a CID (which identifies the specific version).
+ *
+ * @param uri - The AT-URI of the record
+ * @param cid - The CID (Content Identifier) of the record version
+ * @returns A strongRef object
+ *
+ * @example
+ * ```typescript
+ * const ref = createStrongRef(
+ *   "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ *   "bafyreiabc123..."
+ * );
+ * console.log(ref);
+ * // {
+ * //   uri: "at://did:plc:abc123/org.hypercerts.claim.activity/3km2vj4kfqp2a",
+ * //   cid: "bafyreiabc123..."
+ * // }
+ * ```
+ */
+function createStrongRef(uri, cid) {
+    if (!uri || !cid) {
+        throw new Error("Both uri and cid are required to create a strongRef");
     }
-    /**
-     * The configured SDS (Shared Data Server) URL.
-     *
-     * @returns The SDS URL if configured, otherwise `undefined`
-     */
-    get sdsUrl() {
-        return this.config.servers?.sds;
+    return { uri, cid };
+}
+/**
+ * Create a strongRef from a CreateResult or UpdateResult.
+ *
+ * This is a convenience function that extracts the URI and CID from
+ * the result of a record creation or update operation.
+ *
+ * @param result - The result from creating or updating a record
+ * @returns A strongRef object
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({
+ *   title: "Climate Research",
+ *   // ... other params
+ * });
+ *
+ * const ref = createStrongRefFromResult(hypercert);
+ * // Now use ref in another record to reference this hypercert
+ * ```
+ */
+function createStrongRefFromResult(result) {
+    return createStrongRef(result.uri, result.cid);
+}
+/**
+ * Validate that an object is a valid strongRef.
+ *
+ * Checks that the object has the required `uri` and `cid` properties
+ * and that they are non-empty strings.
+ *
+ * @param ref - The object to validate
+ * @returns True if the object is a valid strongRef, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const maybeRef = { uri: "at://...", cid: "bafyrei..." };
+ * if (validateStrongRef(maybeRef)) {
+ *   // Safe to use as strongRef
+ *   record.subject = maybeRef;
+ * }
+ * ```
+ */
+function validateStrongRef(ref) {
+    if (!ref || typeof ref !== "object") {
+        return false;
     }
+    const obj = ref;
+    return typeof obj.uri === "string" && obj.uri.length > 0 && typeof obj.cid === "string" && obj.cid.length > 0;
 }
 /**
- * Factory function to create an ATProto SDK instance.
+ * Type guard to check if a value is a strongRef.
  *
- * This is a convenience function equivalent to `new ATProtoSDK(config)`.
+ * This is an alias for `validateStrongRef` that provides better semantics
+ * for type narrowing in TypeScript.
  *
- * @param config - SDK configuration
- * @returns A new {@link ATProtoSDK} instance
+ * @param value - The value to check
+ * @returns True if the value is a strongRef, false otherwise
  *
  * @example
  * ```typescript
- * import { createATProtoSDK } from "@hypercerts-org/sdk";
+ * function processReference(ref: unknown) {
+ *   if (isStrongRef(ref)) {
+ *     // TypeScript knows ref is StrongRef here
+ *     console.log(ref.uri);
+ *   }
+ * }
+ * ```
+ */
+function isStrongRef(value) {
+    return validateStrongRef(value);
+}
+
+/**
+ * Lexicon Builder Utilities
  *
- * const sdk = createATProtoSDK({
- *   oauth: { ... },
- *   servers: { pds: "https://bsky.social" },
+ * This module provides utilities for constructing lexicon JSON schemas programmatically.
+ * These builders help developers create valid AT Protocol lexicons with proper structure
+ * and type-safe field definitions.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create a string field definition.
+ *
+ * @param options - String field options
+ * @returns A lexicon string field definition
+ *
+ * @example
+ * ```typescript
+ * const titleField = createStringField({
+ *   description: "Title of the item",
+ *   minLength: 1,
+ *   maxLength: 200,
  * });
  * ```
  */
-function createATProtoSDK(config) {
-    return new ATProtoSDK(config);
+function createStringField(options = {}) {
+    return { type: "string", ...options };
+}
+/**
+ * Create an integer field definition.
+ *
+ * @param options - Integer field options
+ * @returns A lexicon integer field definition
+ *
+ * @example
+ * ```typescript
+ * const scoreField = createIntegerField({
+ *   description: "Score from 0 to 100",
+ *   minimum: 0,
+ *   maximum: 100,
+ * });
+ * ```
+ */
+function createIntegerField(options = {}) {
+    return { type: "integer", ...options };
+}
+/**
+ * Create a number field definition.
+ *
+ * @param options - Number field options
+ * @returns A lexicon number field definition
+ *
+ * @example
+ * ```typescript
+ * const weightField = createNumberField({
+ *   description: "Weight as decimal",
+ *   minimum: 0,
+ *   maximum: 1,
+ * });
+ * ```
+ */
+function createNumberField(options = {}) {
+    return { type: "number", ...options };
+}
+/**
+ * Create a boolean field definition.
+ *
+ * @param options - Boolean field options
+ * @returns A lexicon boolean field definition
+ *
+ * @example
+ * ```typescript
+ * const verifiedField = createBooleanField({
+ *   description: "Whether the item is verified",
+ *   default: false,
+ * });
+ * ```
+ */
+function createBooleanField(options = {}) {
+    return { type: "boolean", ...options };
+}
+/**
+ * Create a strongRef field definition.
+ *
+ * StrongRefs are the standard way to reference other records in AT Protocol.
+ * They contain both the AT-URI and CID of the referenced record.
+ *
+ * @param options - Reference field options
+ * @returns A lexicon reference field definition
+ *
+ * @example
+ * ```typescript
+ * const subjectField = createStrongRefField({
+ *   description: "The hypercert being evaluated",
+ * });
+ * ```
+ */
+function createStrongRefField(options = {}) {
+    return {
+        type: "ref",
+        ref: options.ref || "com.atproto.repo.strongRef",
+        description: options.description,
+    };
+}
+/**
+ * Create an array field definition.
+ *
+ * @param itemType - The type of items in the array
+ * @param options - Array field options
+ * @returns A lexicon array field definition
+ *
+ * @example
+ * ```typescript
+ * const tagsField = createArrayField(
+ *   createStringField({ maxLength: 50 }),
+ *   {
+ *     description: "List of tags",
+ *     minLength: 1,
+ *     maxLength: 10,
+ *   }
+ * );
+ * ```
+ */
+function createArrayField(itemType, options = {}) {
+    return {
+        type: "array",
+        items: itemType,
+        ...options,
+    };
+}
+/**
+ * Create an object field definition.
+ *
+ * @param options - Object field options
+ * @returns A lexicon object field definition
+ *
+ * @example
+ * ```typescript
+ * const metadataField = createObjectField({
+ *   description: "Additional metadata",
+ *   properties: {
+ *     author: createStringField(),
+ *     version: createIntegerField(),
+ *   },
+ *   required: ["author"],
+ * });
+ * ```
+ */
+function createObjectField(options = {}) {
+    return { type: "object", ...options };
+}
+/**
+ * Create a blob field definition.
+ *
+ * @param options - Blob field options
+ * @returns A lexicon blob field definition
+ *
+ * @example
+ * ```typescript
+ * const imageField = createBlobField({
+ *   description: "Profile image",
+ *   accept: ["image/png", "image/jpeg"],
+ *   maxSize: 1000000, // 1MB
+ * });
+ * ```
+ */
+function createBlobField(options = {}) {
+    return { type: "blob", ...options };
+}
+/**
+ * Create a datetime string field.
+ *
+ * This is a convenience function for creating string fields with datetime format.
+ *
+ * @param options - String field options
+ * @returns A lexicon string field with datetime format
+ *
+ * @example
+ * ```typescript
+ * const createdAtField = createDatetimeField({
+ *   description: "When the record was created",
+ * });
+ * ```
+ */
+function createDatetimeField(options = {}) {
+    return {
+        type: "string",
+        format: "datetime",
+        ...options,
+    };
+}
+/**
+ * Create a record definition.
+ *
+ * This defines the structure of records in your lexicon.
+ *
+ * @param properties - The record's properties (fields)
+ * @param required - Array of required field names
+ * @param keyType - The type of record key ("tid" for server-generated, "any" for custom)
+ * @returns A lexicon record definition
+ *
+ * @example
+ * ```typescript
+ * const recordDef = createRecordDef(
+ *   {
+ *     $type: createStringField({ const: "org.myapp.evaluation" }),
+ *     subject: createStrongRefField({ description: "The evaluated item" }),
+ *     score: createIntegerField({ minimum: 0, maximum: 100 }),
+ *     createdAt: createDatetimeField(),
+ *   },
+ *   ["$type", "subject", "score", "createdAt"],
+ *   "tid"
+ * );
+ * ```
+ */
+function createRecordDef(properties, required, keyType = "tid") {
+    return {
+        type: "record",
+        key: keyType,
+        record: {
+            type: "object",
+            required,
+            properties,
+        },
+    };
+}
+/**
+ * Create a complete lexicon document.
+ *
+ * This creates a full lexicon JSON structure that can be registered with the SDK.
+ *
+ * @param nsid - The NSID (Namespaced Identifier) for this lexicon
+ * @param properties - The record's properties (fields)
+ * @param required - Array of required field names
+ * @param keyType - The type of record key ("tid" for server-generated, "any" for custom)
+ * @returns A complete lexicon document
+ *
+ * @example
+ * ```typescript
+ * const lexicon = createLexiconDoc(
+ *   "org.myapp.evaluation",
+ *   {
+ *     $type: createStringField({ const: "org.myapp.evaluation" }),
+ *     subject: createStrongRefField({ description: "The evaluated item" }),
+ *     score: createIntegerField({ minimum: 0, maximum: 100 }),
+ *     methodology: createStringField({ maxLength: 500 }),
+ *     createdAt: createDatetimeField(),
+ *   },
+ *   ["$type", "subject", "score", "createdAt"],
+ *   "tid"
+ * );
+ *
+ * // Register with SDK
+ * sdk.getLexiconRegistry().registerFromJSON(lexicon);
+ * ```
+ */
+function createLexiconDoc(nsid, properties, required, keyType = "tid") {
+    return {
+        lexicon: 1,
+        id: nsid,
+        defs: {
+            main: createRecordDef(properties, required, keyType),
+        },
+    };
+}
+/**
+ * Validate a lexicon document structure.
+ *
+ * Performs basic validation to ensure the lexicon follows AT Protocol conventions.
+ * This does NOT perform full JSON schema validation.
+ *
+ * @param lexicon - The lexicon document to validate
+ * @returns True if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const lexicon = createLexiconDoc(...);
+ * if (validateLexiconStructure(lexicon)) {
+ *   sdk.getLexiconRegistry().registerFromJSON(lexicon);
+ * } else {
+ *   console.error("Invalid lexicon structure");
+ * }
+ * ```
+ */
+function validateLexiconStructure(lexicon) {
+    if (!lexicon || typeof lexicon !== "object") {
+        return false;
+    }
+    const doc = lexicon;
+    // Check required top-level fields
+    if (doc.lexicon !== 1)
+        return false;
+    if (typeof doc.id !== "string" || !doc.id)
+        return false;
+    if (!doc.defs || typeof doc.defs !== "object")
+        return false;
+    const defs = doc.defs;
+    if (!defs.main || typeof defs.main !== "object")
+        return false;
+    const main = defs.main;
+    if (main.type !== "record")
+        return false;
+    if (!main.record || typeof main.record !== "object")
+        return false;
+    const record = main.record;
+    if (record.type !== "object")
+        return false;
+    if (!Array.isArray(record.required))
+        return false;
+    if (!record.properties || typeof record.properties !== "object")
+        return false;
+    return true;
+}
+
+/**
+ * Sidecar Pattern Utilities
+ *
+ * This module provides utilities for implementing the AT Protocol "sidecar pattern"
+ * where additional records are created that reference a main record via StrongRef.
+ *
+ * ## The Sidecar Pattern
+ *
+ * In AT Protocol, the sidecar pattern uses **unidirectional references**:
+ * - Sidecar records contain a StrongRef (uri + cid) pointing to the main record
+ * - Main records do NOT maintain back-references to sidecars
+ * - Sidecars are discovered by querying records that reference the main record
+ * - Optionally, sidecars can use the same rkey as the main record (in different collections)
+ *
+ * ## Example Use Cases
+ *
+ * - Evaluations that reference hypercerts
+ * - Comments that reference posts
+ * - Metadata records that reference primary entities
+ *
+ * @see https://atproto.com/specs/record-key
+ * @see https://atproto.com/specs/data-model
+ *
+ * @packageDocumentation
+ */
+/**
+ * Create a sidecar record that references an existing record.
+ *
+ * This is a low-level utility that creates a single sidecar record. The sidecar
+ * record should include a strongRef field that points to the main record.
+ *
+ * @param repo - The repository instance
+ * @param collection - The collection NSID for the sidecar
+ * @param record - The sidecar record data (should include a strongRef to the main record)
+ * @param options - Optional creation options
+ * @returns The created sidecar record
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({...});
+ *
+ * const evaluation = await createSidecarRecord(
+ *   repo,
+ *   "org.myapp.evaluation",
+ *   {
+ *     $type: "org.myapp.evaluation",
+ *     subject: { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid },
+ *     score: 85,
+ *     createdAt: new Date().toISOString(),
+ *   }
+ * );
+ * ```
+ */
+async function createSidecarRecord(repo, collection, record, options = {}) {
+    return await repo.records.create({
+        collection,
+        record,
+        rkey: options.rkey,
+    });
+}
+/**
+ * Attach a sidecar record to an existing main record.
+ *
+ * This creates a new record that references an existing record via strongRef.
+ * It's a higher-level convenience function that wraps `createSidecarRecord`.
+ *
+ * @param repo - The repository instance
+ * @param params - Parameters including the main record reference and sidecar definition
+ * @returns Both the main record reference and the created sidecar
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({...});
+ *
+ * const result = await attachSidecar(repo, {
+ *   mainRecord: {
+ *     uri: hypercert.hypercertUri,
+ *     cid: hypercert.hypercertCid,
+ *   },
+ *   sidecar: {
+ *     collection: "org.myapp.evaluation",
+ *     record: {
+ *       $type: "org.myapp.evaluation",
+ *       subject: { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid },
+ *       score: 85,
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+async function attachSidecar(repo, params) {
+    const sidecarRecord = await createSidecarRecord(repo, params.sidecar.collection, params.sidecar.record, {
+        rkey: params.sidecar.rkey,
+    });
+    return {
+        mainRecord: params.mainRecord,
+        sidecarRecord,
+    };
+}
+/**
+ * Create a main record and multiple sidecar records in sequence.
+ *
+ * This orchestrates the creation of a main record followed by one or more
+ * sidecar records that reference it. This is useful for workflows like:
+ * - Creating a project with multiple hypercert claims
+ * - Creating a hypercert with evidence and evaluation records
+ *
+ * @param repo - The repository instance
+ * @param params - Parameters including the main record and sidecar definitions
+ * @returns The main record and all created sidecar records
+ *
+ * @example
+ * ```typescript
+ * const result = await createWithSidecars(repo, {
+ *   main: {
+ *     collection: "org.hypercerts.project",
+ *     record: {
+ *       $type: "org.hypercerts.project",
+ *       title: "Climate Initiative 2024",
+ *       description: "Our climate work",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ *   sidecars: [
+ *     {
+ *       collection: "org.hypercerts.claim.activity",
+ *       record: {
+ *         $type: "org.hypercerts.claim.activity",
+ *         title: "Tree Planting",
+ *         // ... other hypercert fields
+ *         // Note: If you need to reference the main record, you must wait
+ *         // for result.main and then call batchCreateSidecars separately
+ *       },
+ *     },
+ *     {
+ *       collection: "org.hypercerts.claim.activity",
+ *       record: {
+ *         $type: "org.hypercerts.claim.activity",
+ *         title: "Carbon Measurement",
+ *         // ... other hypercert fields
+ *       },
+ *     },
+ *   ],
+ * });
+ *
+ * console.log(result.main.uri); // Main project record
+ * console.log(result.sidecars.length); // 2 hypercert sidecars
+ * ```
+ */
+async function createWithSidecars(repo, params) {
+    // Create the main record first
+    const main = await repo.records.create({
+        collection: params.main.collection,
+        record: params.main.record,
+        rkey: params.main.rkey,
+    });
+    // Create all sidecar records
+    const sidecars = [];
+    for (const sidecar of params.sidecars) {
+        const created = await repo.records.create({
+            collection: sidecar.collection,
+            record: sidecar.record,
+            rkey: sidecar.rkey,
+        });
+        sidecars.push(created);
+    }
+    return { main, sidecars };
+}
+/**
+ * Batch create multiple sidecar records.
+ *
+ * This is useful when you want to add multiple related records
+ * efficiently. The sidecar records should already contain any necessary
+ * references to the main record in their data.
+ *
+ * @param repo - The repository instance
+ * @param sidecars - Array of sidecar definitions (records should include references)
+ * @returns Array of created sidecar records
+ *
+ * @example
+ * ```typescript
+ * const hypercert = await repo.hypercerts.create({...});
+ * const mainRef = { uri: hypercert.hypercertUri, cid: hypercert.hypercertCid };
+ *
+ * const evaluations = await batchCreateSidecars(repo, [
+ *   {
+ *     collection: "org.myapp.evaluation",
+ *     record: {
+ *       $type: "org.myapp.evaluation",
+ *       subject: mainRef,  // Reference already included
+ *       score: 85,
+ *       methodology: "Peer review",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ *   {
+ *     collection: "org.myapp.comment",
+ *     record: {
+ *       $type: "org.myapp.comment",
+ *       subject: mainRef,  // Reference already included
+ *       text: "Great work!",
+ *       createdAt: new Date().toISOString(),
+ *     },
+ *   },
+ * ]);
+ * ```
+ */
+async function batchCreateSidecars(repo, sidecars) {
+    const results = [];
+    for (const sidecar of sidecars) {
+        const result = await createSidecarRecord(repo, sidecar.collection, sidecar.record, {
+            rkey: sidecar.rkey,
+        });
+        results.push(result);
+    }
+    return results;
 }
 
 /**
@@ -5825,9 +8072,13 @@ Object.defineProperty(exports, "OrgHypercertsClaimCollection", {
     enumerable: true,
     get: function () { return lexicon.OrgHypercertsClaimCollection; }
 });
-Object.defineProperty(exports, "OrgHypercertsClaimContribution", {
+Object.defineProperty(exports, "OrgHypercertsClaimContributionDetails", {
+    enumerable: true,
+    get: function () { return lexicon.OrgHypercertsClaimContributionDetails; }
+});
+Object.defineProperty(exports, "OrgHypercertsClaimContributorInformation", {
     enumerable: true,
-    get: function () { return lexicon.OrgHypercertsClaimContribution; }
+    get: function () { return lexicon.OrgHypercertsClaimContributorInformation; }
 });
 Object.defineProperty(exports, "OrgHypercertsClaimEvaluation", {
     enumerable: true,
@@ -5841,10 +8092,6 @@ Object.defineProperty(exports, "OrgHypercertsClaimMeasurement", {
     enumerable: true,
     get: function () { return lexicon.OrgHypercertsClaimMeasurement; }
 });
-Object.defineProperty(exports, "OrgHypercertsClaimProject", {
-    enumerable: true,
-    get: function () { return lexicon.OrgHypercertsClaimProject; }
-});
 Object.defineProperty(exports, "OrgHypercertsClaimRights", {
     enumerable: true,
     get: function () { return lexicon.OrgHypercertsClaimRights; }
@@ -5853,6 +8100,10 @@ Object.defineProperty(exports, "OrgHypercertsFundingReceipt", {
     enumerable: true,
     get: function () { return lexicon.OrgHypercertsFundingReceipt; }
 });
+Object.defineProperty(exports, "OrgHypercertsHelperWorkScopeTag", {
+    enumerable: true,
+    get: function () { return lexicon.OrgHypercertsHelperWorkScopeTag; }
+});
 Object.defineProperty(exports, "validate", {
     enumerable: true,
     get: function () { return lexicon.validate; }
@@ -5865,6 +8116,7 @@ exports.AccountActionSchema = AccountActionSchema;
 exports.AccountAttrSchema = AccountAttrSchema;
 exports.AccountPermissionSchema = AccountPermissionSchema;
 exports.AuthenticationError = AuthenticationError;
+exports.BaseOperations = BaseOperations;
 exports.BlobPermissionSchema = BlobPermissionSchema;
 exports.CollaboratorPermissionsSchema = CollaboratorPermissionsSchema;
 exports.CollaboratorSchema = CollaboratorSchema;
@@ -5876,6 +8128,7 @@ exports.IdentityPermissionSchema = IdentityPermissionSchema;
 exports.InMemorySessionStore = InMemorySessionStore;
 exports.InMemoryStateStore = InMemoryStateStore;
 exports.IncludePermissionSchema = IncludePermissionSchema;
+exports.LexiconRegistry = LexiconRegistry;
 exports.MimeTypeSchema = MimeTypeSchema;
 exports.NetworkError = NetworkError;
 exports.NsidSchema = NsidSchema;
@@ -5895,13 +8148,37 @@ exports.TRANSITION_SCOPES = TRANSITION_SCOPES;
 exports.TimeoutConfigSchema = TimeoutConfigSchema;
 exports.TransitionScopeSchema = TransitionScopeSchema;
 exports.ValidationError = ValidationError;
+exports.attachSidecar = attachSidecar;
+exports.batchCreateSidecars = batchCreateSidecars;
+exports.buildAtUri = buildAtUri;
 exports.buildScope = buildScope;
 exports.createATProtoSDK = createATProtoSDK;
+exports.createArrayField = createArrayField;
+exports.createBlobField = createBlobField;
+exports.createBooleanField = createBooleanField;
+exports.createDatetimeField = createDatetimeField;
+exports.createIntegerField = createIntegerField;
+exports.createLexiconDoc = createLexiconDoc;
+exports.createNumberField = createNumberField;
+exports.createObjectField = createObjectField;
+exports.createRecordDef = createRecordDef;
+exports.createSidecarRecord = createSidecarRecord;
+exports.createStringField = createStringField;
+exports.createStrongRef = createStrongRef;
+exports.createStrongRefField = createStrongRefField;
+exports.createStrongRefFromResult = createStrongRefFromResult;
+exports.createWithSidecars = createWithSidecars;
+exports.extractRkeyFromUri = extractRkeyFromUri;
 exports.hasAllPermissions = hasAllPermissions;
 exports.hasAnyPermission = hasAnyPermission;
 exports.hasPermission = hasPermission;
+exports.isStrongRef = isStrongRef;
+exports.isValidAtUri = isValidAtUri;
 exports.mergeScopes = mergeScopes;
+exports.parseAtUri = parseAtUri;
 exports.parseScope = parseScope;
 exports.removePermissions = removePermissions;
+exports.validateLexiconStructure = validateLexiconStructure;
 exports.validateScope = validateScope;
+exports.validateStrongRef = validateStrongRef;
 //# sourceMappingURL=index.cjs.map