@resourcexjs/core 2.7.0 → 2.9.0

package/dist/index.d.ts

@@ -1,23 +1,22 @@
 /**
-* ResourceX Error hierarchy
+* RXA - ResourceX Archive
+*
+* Archive container (tar.gz format) for storage and transfer.
 */
-declare class ResourceXError extends Error {
-	constructor(message: string, options?: ErrorOptions);
-}
-declare class LocatorError extends ResourceXError {
-	readonly locator?: string;
-	constructor(message: string, locator?: string);
-}
-declare class ManifestError extends ResourceXError {
-	constructor(message: string);
-}
-declare class ContentError extends ResourceXError {
-	constructor(message: string);
-}
-declare class DefinitionError extends ResourceXError {
-	constructor(message: string);
+interface RXA {
+	/** Content as a readable stream (tar.gz format) */
+	readonly stream: ReadableStream<Uint8Array>;
+	/** Get raw archive buffer (tar.gz format) */
+	buffer(): Promise<Buffer>;
 }
 /**
+* Create RXA from files.
+*
+* @param files - Record of file paths to Buffer contents
+* @returns RXA archive object
+*/
+declare function archive(files: Record<string, Buffer>): Promise<RXA>;
+/**
 * RXD - ResourceX Definition
 *
 * The content of resource.json file.
@@ -37,6 +36,21 @@ interface RXD {
 	readonly [key: string]: unknown;
 }
 /**
+* Parse and validate a resource definition (resource.json content).
+*
+* @param input - The raw JSON object to parse
+* @returns A validated RXD object
+* @throws DefinitionError if validation fails
+*/
+declare function define(input: unknown): RXD;
+/**
+* Extract files from RXA.
+*
+* @param rxa - Resource archive
+* @returns Record of file paths to Buffer contents
+*/
+declare function extract(rxa: RXA): Promise<Record<string, Buffer>>;
+/**
 * RXL - ResourceX Locator
 *
 * Unique identifier for a resource (pure data object).
@@ -62,62 +76,73 @@ interface RXL {
 	readonly tag: string;
 }
 /**
+* Format RXL to locator string.
+*
+* Docker-style format: [registry/][path/]name[:tag]
+*
+* Examples:
+* - { name: "hello", tag: "latest" } → "hello" (omit :latest)
+* - { name: "hello", tag: "1.0.0" } → "hello:1.0.0"
+* - { registry: "localhost:3098", name: "hello", tag: "1.0.0" } → "localhost:3098/hello:1.0.0"
+*
+* @param rxl - Resource locator
+* @returns Locator string
+*/
+declare function format(rxl: RXL): string;
+/**
 * RXM - ResourceX Manifest
 *
-* Resource metadata stored within the resource (pure data object).
+* Resource context representation organized by RX primitives.
+* Structure: definition (RXD) + archive (RXA) + source (RXS)
 */
-interface RXM {
-	readonly registry?: string;
-	readonly path?: string;
+/**
+* RXM Definition — what the resource IS.
+* Sourced from RXD (resource.json).
+*/
+interface RXMDefinition {
 	readonly name: string;
 	readonly type: string;
 	readonly tag: string;
-	readonly files?: string[];
+	readonly registry?: string;
+	readonly path?: string;
+	readonly description?: string;
+	readonly author?: string;
+	readonly license?: string;
+	readonly keywords?: string[];
+	readonly repository?: string;
 }
 /**
-* RXA - ResourceX Archive
-*
-* Archive container (tar.gz format) for storage and transfer.
+* RXM Archive — packaging metadata.
+* Placeholder for future fields (digest, size, md5, etc.)
 */
-interface RXA {
-	/** Content as a readable stream (tar.gz format) */
-	readonly stream: ReadableStream<Uint8Array>;
-	/** Get raw archive buffer (tar.gz format) */
-	buffer(): Promise<Buffer>;
-}
+type RXMArchive = {};
 /**
-* RXR - ResourceX Resource
-*
-* Complete resource object combining locator, manifest, and archive.
+* File entry with metadata.
 */
-interface RXR {
-	readonly locator: RXL;
-	readonly manifest: RXM;
-	readonly archive: RXA;
+interface FileEntry {
+	readonly size: number;
 }
 /**
-* Parse and validate a resource definition (resource.json content).
-*
-* @param input - The raw JSON object to parse
-* @returns A validated RXD object
-* @throws DefinitionError if validation fails
-*/
-declare function define(input: unknown): RXD;
-/**
-* Create RXM from RXD.
-* Extracts only the core metadata fields (pure data object).
-*
-* @param rxd - Resource definition
-* @returns RXM manifest object
+* Recursive file tree structure.
+* Keys ending with '/' are directories containing nested FileTree.
+* Other keys are files with FileEntry metadata.
 */
-declare function manifest(rxd: RXD): RXM;
+type FileTree = {
+	readonly [key: string]: FileEntry | FileTree
+};
 /**
-* Create RXA from files.
-*
-* @param files - Record of file paths to Buffer contents
-* @returns RXA archive object
+* RXM Source — what's IN the resource.
+* File structure and content preview.
 */
-declare function archive(files: Record<string, Buffer>): Promise<RXA>;
+interface RXMSource {
+	readonly files?: FileTree;
+	readonly preview?: string;
+}
+interface RXM {
+	readonly definition: RXMDefinition;
+	readonly archive: RXMArchive;
+	readonly source: RXMSource;
+}
 /**
 * Create RXL from RXM.
 *
@@ -126,34 +151,13 @@ declare function archive(files: Record<string, Buffer>): Promise<RXA>;
 */
 declare function locate(rxm: RXM): RXL;
 /**
-* Create RXR from RXM and RXA.
-*
-* @param rxm - Resource manifest
-* @param rxa - Resource archive
-* @returns RXR resource object
-*/
-declare function resource(rxm: RXM, rxa: RXA): RXR;
-/**
-* Extract files from RXA.
-*
-* @param rxa - Resource archive
-* @returns Record of file paths to Buffer contents
-*/
-declare function extract(rxa: RXA): Promise<Record<string, Buffer>>;
-/**
-* Format RXL to locator string.
-*
-* Docker-style format: [registry/][path/]name[:tag]
-*
-* Examples:
-* - { name: "hello", tag: "latest" } → "hello" (omit :latest)
-* - { name: "hello", tag: "1.0.0" } → "hello:1.0.0"
-* - { registry: "localhost:3098", name: "hello", tag: "1.0.0" } → "localhost:3098/hello:1.0.0"
+* Create RXM from RXD.
+* Maps RXD fields into the structured RXM format.
 *
-* @param rxl - Resource locator
-* @returns Locator string
+* @param rxd - Resource definition
+* @returns RXM manifest object
 */
-declare function format(rxl: RXL): string;
+declare function manifest(rxd: RXD): RXM;
 /**
 * Parse locator string to RXL.
 *
@@ -171,6 +175,39 @@ declare function format(rxl: RXL): string;
 */
 declare function parse(locator: string): RXL;
 /**
+* RXR - ResourceX Resource
+*
+* Complete resource object combining locator, manifest, and archive.
+*/
+interface RXR {
+	readonly locator: RXL;
+	readonly manifest: RXM;
+	readonly archive: RXA;
+}
+/**
+* Create RXR from RXM and RXA.
+*
+* @param rxm - Resource manifest
+* @param rxa - Resource archive
+* @returns RXR resource object
+*/
+declare function resource(rxm: RXM, rxa: RXA): RXR;
+/**
+* RXS - ResourceX Source
+*
+* Intermediate representation of raw files from any source.
+* Produced by SourceLoader, consumed by TypeDetectorChain.
+*
+* Unlike RXR (which is fully packaged), RXS is pre-detection:
+* the files have been loaded but the type and metadata are unknown.
+*/
+interface RXS {
+	/** Original source identifier (path, URL, etc.) */
+	readonly source: string;
+	/** Raw files loaded from source: relative path -> content */
+	readonly files: Record<string, Buffer>;
+}
+/**
 * Wrap existing tar.gz buffer as RXA.
 *
 * @param buffer - Existing tar.gz buffer
@@ -178,243 +215,178 @@ declare function parse(locator: string): RXL;
 */
 declare function wrap(buffer: Buffer): RXA;
 /**
-* Isolator type for resolver execution.
-* Matches SandboX isolator types directly.
-* Configured at Registry level, not per-type.
+* TypeDetector - Strategy interface for detecting resource type from files.
 *
-* - "none": No isolation, fastest (~10ms), for development
-* - "srt": OS-level isolation (~50ms), secure local dev
-* - "cloudflare": Container isolation (~100ms), local Docker or edge
-* - "e2b": MicroVM isolation (~150ms), production (planned)
+* Detectors examine file contents and structure to determine
+* the resource type and extract metadata.
 */
-type IsolatorType = "none" | "srt" | "cloudflare" | "e2b";
 /**
-* ResolveContext - Pure data context passed to resolver in sandbox.
-*
-* This is a serializable data structure that replaces RXR for sandbox execution.
-* The executor pre-processes RXR (extracts files) before passing to resolver.
+* Result of type detection.
+* Fields map directly to RXD fields for generateDefinition().
 */
-interface ResolveContext {
-	/**
-	* Resource manifest metadata.
-	*/
-	manifest: {
-		domain: string
-		path?: string
-		name: string
-		type: string
-		version: string
-	};
+interface TypeDetectionResult {
+	/** Detected resource type (e.g., "skill", "text") */
+	readonly type: string;
+	/** Detected resource name */
+	readonly name: string;
+	/** Tag/version (defaults to "latest" if not provided) */
+	readonly tag?: string;
+	/** Description extracted from content */
+	readonly description?: string;
+	/** Registry for the resource */
+	readonly registry?: string;
+	/** Path within registry */
+	readonly path?: string;
+	/** Author information */
+	readonly author?: string;
+	/** License information */
+	readonly license?: string;
+	/** Keywords for searchability */
+	readonly keywords?: string[];
+	/** Repository URL */
+	readonly repository?: string;
 	/**
-	* Extracted files from archive.
-	* Key is file path, value is file content as Uint8Array.
+	* Files to exclude from the content archive.
+	* E.g., ["resource.json"] — metadata files, not content.
 	*/
-	files: Record<string, Uint8Array>;
+	readonly excludeFromContent?: string[];
 }
 /**
-* BundledType - Pre-bundled resource type ready for execution.
-* Contains bundled code string instead of closure.
+* TypeDetector - detects resource type from raw files.
 *
-* Note: Sandbox isolation is configured at Registry level via createRegistry({ sandbox: ... })
+* Follows the Chain of Responsibility pattern (like TypeHandlerChain).
 */
-interface BundledType {
+interface TypeDetector {
+	/** Detector name (for debugging and logging) */
+	readonly name: string;
 	/**
-	* Type name (e.g., "text", "json", "prompt").
+	* Detect the resource type from the given files.
+	*
+	* @param files - Raw files from the source
+	* @param source - Original source identifier (for deriving name)
+	* @returns Detection result, or null if this detector cannot handle the files
 	*/
-	name: string;
+	detect(files: Record<string, Buffer>, source: string): TypeDetectionResult | null;
+}
+/**
+* Generate an RXD from a TypeDetectionResult.
+*
+* Maps detection result fields to the RXD schema and validates
+* through the existing define() function.
+*
+* @param result - Detection result from TypeDetectorChain
+* @returns Validated RXD
+* @throws DefinitionError if the result produces invalid RXD
+*/
+declare function generateDefinition(result: TypeDetectionResult): RXD;
+/**
+* ResourceJsonDetector - Detects resources with an explicit resource.json.
+*
+* Highest-priority detector. When resource.json exists,
+* it takes precedence over all other detectors.
+*/
+declare class ResourceJsonDetector implements TypeDetector {
+	readonly name = "resource-json";
+	detect(files: Record<string, Buffer>, _source: string): TypeDetectionResult | null;
+}
+/**
+* SkillDetector - Detects Agent Skill resources from SKILL.md.
+*
+* Pattern:
+* - Required: SKILL.md file
+* - Optional: references/ directory
+*
+* SKILL.md is content (kept in archive), not metadata.
+*/
+declare class SkillDetector implements TypeDetector {
+	readonly name = "skill";
+	detect(files: Record<string, Buffer>, source: string): TypeDetectionResult | null;
 	/**
-	* Alternative names for this type.
+	* Extract description from the first markdown heading.
 	*/
-	aliases?: string[];
+	private extractDescription;
+}
+/**
+* TypeDetectorChain - Chain of type detectors.
+*
+* Follows the same pattern as TypeHandlerChain:
+* - Static create() factory with built-in detectors
+* - Extensible via register()
+* - First match wins
+*
+* Detection order:
+* 1. ResourceJsonDetector (explicit resource.json always wins)
+* 2. SkillDetector (SKILL.md pattern)
+* 3. Custom detectors (registered in order)
+*/
+declare class TypeDetectorChain {
+	private readonly detectors;
+	private constructor();
 	/**
-	* Human-readable description.
+	* Create a new TypeDetectorChain with built-in detectors.
 	*/
-	description: string;
+	static create(): TypeDetectorChain;
 	/**
-	* JSON Schema for resolver arguments.
+	* Register a custom detector.
+	* Custom detectors are appended after built-in detectors.
 	*/
-	schema?: JSONSchema;
+	register(detector: TypeDetector): void;
 	/**
-	* Bundled resolver code (executable in sandbox).
+	* Detect type from files.
+	*
+	* @param files - Raw files from the source
+	* @param source - Original source identifier
+	* @returns Detection result
+	* @throws ResourceXError if no detector matches
 	*/
-	code: string;
+	detect(files: Record<string, Buffer>, source: string): TypeDetectionResult;
 }
 /**
-* JSON Schema property definition.
+* ResourceX Error hierarchy
 */
-interface JSONSchemaProperty {
-	type: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
-	description?: string;
-	default?: unknown;
-	enum?: unknown[];
-	items?: JSONSchemaProperty;
-	properties?: Record<string, JSONSchemaProperty>;
-	required?: string[];
+declare class ResourceXError extends Error {
+	constructor(message: string, options?: ErrorOptions);
 }
-/**
-* JSON Schema definition for resolver arguments.
-* Used by UI to render parameter forms.
-*/
-interface JSONSchema extends JSONSchemaProperty {
-	$schema?: string;
-	title?: string;
+declare class LocatorError extends ResourceXError {
+	readonly locator?: string;
+	constructor(message: string, locator?: string);
 }
-/**
-* ResolvedResource - Structured result object returned by resolver.
-* Contains execute function, original resource, and optional schema for UI rendering.
-*/
-interface ResolvedResource<
-	TArgs = void,
-	TResult = unknown
-> {
-	/**
-	* Original resource object (RXR from @resourcexjs/core).
-	*/
-	resource: unknown;
-	/**
-	* Execute function to get the resource content.
-	* - For static resources (text/json/binary): call with no arguments
-	* - For dynamic resources (tool): call with arguments
-	*/
-	execute: (args?: TArgs) => TResult | Promise<TResult>;
-	/**
-	* JSON Schema for the arguments (undefined if no arguments needed).
-	* UI uses this to render parameter forms.
-	*/
-	schema: TArgs extends void ? undefined : JSONSchema;
-}
-/**
-* ResourceResolver - Transforms resource into a structured result object.
-* The execute function is lazy-loaded: content is only read when called.
-*/
-interface ResourceResolver<
-	TArgs = void,
-	TResult = unknown
-> {
-	/**
-	* JSON Schema for arguments (required if TArgs is not void).
-	* This constraint ensures type safety at definition time.
-	*/
-	schema: TArgs extends void ? undefined : JSONSchema;
-	/**
-	* Resolve resource into a structured result object.
-	* @param rxr - RXR object from @resourcexjs/core
-	*/
-	resolve(rxr: unknown): Promise<ResolvedResource<TArgs, TResult>>;
+declare class ManifestError extends ResourceXError {
+	constructor(message: string);
 }
-/**
-* ResourceType - Defines how a resource type is handled.
-*/
-interface ResourceType<
-	TArgs = void,
-	TResult = unknown
-> {
-	/**
-	* Type name (e.g., "text", "json", "binary").
-	*/
-	name: string;
-	/**
-	* Alternative names for this type (e.g., ["txt", "plaintext"]).
-	*/
-	aliases?: string[];
-	/**
-	* Human-readable description.
-	*/
-	description: string;
-	/**
-	* Resolver to transform RXR into structured result object.
-	*/
-	resolver: ResourceResolver<TArgs, TResult>;
+declare class ContentError extends ResourceXError {
+	constructor(message: string);
 }
-/**
-* Bundle a resource type from a source file.
-*
-* @param sourcePath - Path to the .type.ts file
-* @param basePath - Base path for resolving relative paths (defaults to cwd)
-* @returns BundledType ready for registry
-*
-* @example
-* ```typescript
-* const promptType = await bundleResourceType("./prompt.type.ts");
-* ```
-*/
-declare function bundleResourceType(sourcePath: string, basePath?: string): Promise<BundledType>;
-/**
-* Resource type related error.
-*/
-declare class ResourceTypeError extends ResourceXError {
+declare class DefinitionError extends ResourceXError {
 	constructor(message: string);
 }
 /**
-* TypeHandlerChain - Manages resource type registration.
-*
-* Responsibilities:
-* - Register types (name + aliases)
-* - Look up types by name
-*
-* Execution is delegated to ResolverExecutor (in registry package).
-*
-* Built-in types (text, json, binary) are registered by default.
+* ResourceLoader - Strategy interface for loading resources from different sources.
 */
-declare class TypeHandlerChain {
-	private handlers;
-	private constructor();
-	/**
-	* Create a new TypeHandlerChain instance.
-	* Built-in types (text, json, binary) are included by default.
-	*/
-	static create(): TypeHandlerChain;
-	/**
-	* Internal registration (no duplicate check).
-	*/
-	private registerInternal;
-	/**
-	* Register a type.
-	* @throws ResourceTypeError if type is already registered
-	*/
-	register(type: BundledType): void;
-	/**
-	* Check if a type is supported.
-	*/
-	canHandle(typeName: string): boolean;
-	/**
-	* Get handler for a type.
-	* @throws ResourceTypeError if type is not supported
-	*/
-	getHandler(typeName: string): BundledType;
-	/**
-	* Get handler for a type, or undefined if not found.
-	*/
-	getHandlerOrUndefined(typeName: string): BundledType | undefined;
+interface ResourceLoader {
 	/**
-	* Get all supported type names (including aliases).
+	* Check if this loader can handle the given source.
+	*
+	* @param source - Source path or identifier
+	* @returns true if this loader can handle the source
 	*/
-	getSupportedTypes(): string[];
+	canLoad(source: string): boolean | Promise<boolean>;
 	/**
-	* Clear all registered types (for testing).
+	* Load a resource from the given source.
+	*
+	* @param source - Source path or identifier
+	* @returns Complete RXR object
+	* @throws ResourceXError if loading fails
 	*/
-	clear(): void;
+	load(source: string): Promise<RXR>;
 }
 /**
-* Plain text content
-*/
-declare const textType: BundledType;
-/**
-* JSON content
-*/
-declare const jsonType: BundledType;
-/**
-* Binary content
-*/
-declare const binaryType: BundledType;
-/**
-* All built-in types as an array.
-*/
-declare const builtinTypes: BundledType[];
-/**
-* ResourceLoader - Strategy interface for loading resources from different sources.
+* SourceLoader - Strategy interface for loading raw files from a source.
+*
+* Unlike ResourceLoader (which produces a complete RXR),
+* SourceLoader produces an RXS (raw files) for type detection.
 */
-interface ResourceLoader {
+interface SourceLoader {
 	/**
 	* Check if this loader can handle the given source.
 	*
@@ -423,13 +395,13 @@ interface ResourceLoader {
 	*/
 	canLoad(source: string): boolean | Promise<boolean>;
 	/**
-	* Load a resource from the given source.
+	* Load raw files from the given source.
 	*
 	* @param source - Source path or identifier
-	* @returns Complete RXR object
+	* @returns RXS with raw files
 	* @throws ResourceXError if loading fails
 	*/
-	load(source: string): Promise<RXR>;
+	load(source: string): Promise<RXS>;
 }
 /**
 * Default ResourceLoader implementation for loading resources from folders.
@@ -463,6 +435,39 @@ declare class FolderLoader implements ResourceLoader {
 	private readFolderFiles;
 }
 /**
+* FolderSourceLoader - Loads raw files from a folder into RXS.
+*
+* Unlike FolderLoader (which requires resource.json and produces RXR),
+* FolderSourceLoader loads ALL files from a folder without interpreting them.
+* Type detection happens downstream via TypeDetectorChain.
+*/
+declare class FolderSourceLoader implements SourceLoader {
+	canLoad(source: string): Promise<boolean>;
+	load(source: string): Promise<RXS>;
+	/**
+	* Recursively read all files in a folder.
+	*/
+	private readFolderFiles;
+}
+/**
+* GitHubSourceLoader - Loads raw files from a GitHub directory into RXS.
+*
+* Fetches files via the GitHub Contents API (no authentication required
+* for public repositories).
+*/
+declare class GitHubSourceLoader implements SourceLoader {
+	canLoad(source: string): boolean;
+	load(source: string): Promise<RXS>;
+	/**
+	* Recursively fetch all files from a GitHub directory.
+	*/
+	private fetchDirectory;
+	/**
+	* Fetch a single file's content.
+	*/
+	private fetchFile;
+}
+/**
 * Configuration options for loadResource.
 */
 interface LoadResourceConfig {
@@ -503,53 +508,83 @@ interface LoadResourceConfig {
 */
 declare function loadResource(source: string, config?: LoadResourceConfig): Promise<RXR>;
 /**
-* Search options for querying resources.
-*/
-interface SearchOptions {
-	/**
-	* Search query string (matches against name, domain, path).
-	*/
-	query?: string;
-	/**
-	* Maximum number of results to return.
-	*/
-	limit?: number;
-	/**
-	* Number of results to skip (for pagination).
-	*/
-	offset?: number;
-}
-/**
-* Registry interface - business layer for RXR operations.
+* SourceLoaderChain - Chain of source loaders.
 *
-* This interface defines CRUD operations on RXR objects.
-* Different implementations (HostedRegistry, MirrorRegistry, LinkedRegistry)
-* provide different semantics on top of the same Storage layer.
+* Follows the same pattern as TypeDetectorChain:
+* - Static create() factory with built-in loaders
+* - Extensible via register()
+* - First match wins
+*
+* Loading order:
+* 1. FolderSourceLoader (local directories)
+* 2. GitHubSourceLoader (GitHub URLs)
+* 3. Custom loaders (registered in order)
 */
-interface Registry {
-	/**
-	* Get resource by locator.
-	* @throws RegistryError if not found
-	*/
-	get(rxl: RXL): Promise<RXR>;
+declare class SourceLoaderChain {
+	private readonly loaders;
+	private constructor();
 	/**
-	* Store resource.
+	* Create a new SourceLoaderChain with built-in loaders.
 	*/
-	put(rxr: RXR): Promise<void>;
+	static create(): SourceLoaderChain;
 	/**
-	* Check if resource exists.
+	* Register a custom loader.
+	* Custom loaders are appended after built-in loaders.
 	*/
-	has(rxl: RXL): Promise<boolean>;
+	register(loader: SourceLoader): void;
 	/**
-	* Delete resource.
+	* Check if any loader in the chain can handle the source.
+	*
+	* @param source - Source path or identifier
+	* @returns true if any loader can handle the source
 	*/
-	remove(rxl: RXL): Promise<void>;
+	canLoad(source: string): Promise<boolean>;
 	/**
-	* List resources matching options.
+	* Load raw files from a source.
+	*
+	* @param source - Source path or identifier
+	* @returns RXS with raw files
+	* @throws ResourceXError if no loader matches
 	*/
-	list(options?: SearchOptions): Promise<RXL[]>;
+	load(source: string): Promise<RXS>;
+}
+/**
+* Configuration for resolveSource.
+*/
+interface ResolveSourceConfig {
+	/** Custom loader chain (overrides default chain) */
+	loaderChain?: SourceLoaderChain;
+	/** Additional loaders to register on the chain */
+	loaders?: SourceLoader[];
+	/** Custom detector chain (default: TypeDetectorChain.create()) */
+	detectorChain?: TypeDetectorChain;
+	/** Additional detectors to register on the default chain */
+	detectors?: TypeDetector[];
 }
 /**
+* Resolve a source into a complete RXR.
+*
+* Pipeline: Load files -> Detect type -> Generate RXD -> Archive -> RXR
+*
+* Supports both explicit resource.json and auto-detection from file patterns.
+*
+* @param source - Source path or identifier
+* @param config - Optional configuration
+* @returns Complete RXR ready for registry
+*
+* @example
+* ```typescript
+* // Auto-detect from folder (with or without resource.json)
+* const rxr = await resolveSource("./my-skill");
+*
+* // With custom loader
+* const rxr = await resolveSource("./custom", {
+*   loaders: [new MyCustomLoader()]
+* });
+* ```
+*/
+declare function resolveSource(source: string, config?: ResolveSourceConfig): Promise<RXR>;
+/**
 * RXAStore - Content-Addressable Storage for Resource Archives
 *
 * SPI interface for storing file content by digest (hash).
@@ -596,6 +631,11 @@ interface StoredRXM {
 	readonly name: string;
 	readonly type: string;
 	readonly tag: string;
+	readonly description?: string;
+	readonly author?: string;
+	readonly license?: string;
+	readonly keywords?: string[];
+	readonly repository?: string;
 	readonly files: Record<string, string>;
 	readonly createdAt?: Date;
 	readonly updatedAt?: Date;
@@ -658,19 +698,161 @@ interface RXMStore {
 	* Delete all manifests from a registry (clear cache).
 	*/
 	deleteByRegistry(registry: string): Promise<void>;
-}
-declare class CASRegistry implements Registry {
-	private readonly rxaStore;
-	private readonly rxmStore;
-	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
-	get(rxl: RXL): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
-	has(rxl: RXL): Promise<boolean>;
-	remove(rxl: RXL): Promise<void>;
-	list(options?: SearchOptions): Promise<RXL[]>;
 	/**
-	* Clear cached resources (resources with registry).
-	* @param registry - If provided, only clear resources from this registry
+	* Set the "latest" pointer for a resource.
+	* Points to the tag of the most recently added version.
+	*/
+	setLatest(name: string, tag: string, registry?: string): Promise<void>;
+	/**
+	* Get the "latest" pointer for a resource.
+	* @returns The tag that "latest" points to, or null if no pointer exists.
+	*/
+	getLatest(name: string, registry?: string): Promise<string | null>;
+}
+/**
+* Provider configuration passed to createStores/createLoader.
+*/
+interface ProviderConfig {
+	/**
+	* Base path for storage (filesystem) or connection info.
+	*/
+	path?: string;
+	/**
+	* Platform-specific configuration.
+	*/
+	[key: string]: unknown;
+}
+/**
+* Stores created by the provider.
+*/
+interface ProviderStores {
+	rxaStore: RXAStore;
+	rxmStore: RXMStore;
+}
+/**
+* Resource loader interface for loading from directories/archives.
+*/
+interface ResourceLoader2 {
+	/**
+	* Check if this loader can handle the given source.
+	*/
+	canLoad(source: string): boolean | Promise<boolean>;
+	/**
+	* Load resource from source.
+	*/
+	load(source: string): Promise<unknown>;
+}
+/**
+* ResourceX Provider - Platform implementation interface.
+*
+* Platforms implement this interface to provide storage and loading
+* capabilities for their environment.
+*/
+interface ResourceXProvider {
+	/**
+	* Platform identifier.
+	*/
+	readonly platform: string;
+	/**
+	* Create storage instances for the platform.
+	*/
+	createStores(config: ProviderConfig): ProviderStores;
+	/**
+	* Create resource loader (optional).
+	* Not all platforms support loading from filesystem.
+	*/
+	createLoader?(config: ProviderConfig): ResourceLoader2;
+	/**
+	* Create source loader for auto-detection pipeline (optional).
+	*/
+	createSourceLoader?(config: ProviderConfig): SourceLoader;
+}
+/**
+* Well-known discovery response format.
+*/
+interface WellKnownResponse {
+	version?: string;
+	registries: string[];
+}
+/**
+* Result from discoverRegistry().
+*/
+interface DiscoveryResult {
+	domain: string;
+	registries: string[];
+}
+/**
+* Discover registry for a domain using well-known.
+* @param domain - The domain to discover (e.g., "deepractice.ai")
+* @returns Discovery result with domain and authorized registries
+*/
+declare function discoverRegistry(domain: string): Promise<DiscoveryResult>;
+/**
+* Registry-specific error.
+*/
+declare class RegistryError extends ResourceXError {
+	constructor(message: string, options?: ErrorOptions);
+}
+/**
+* Search options for querying resources.
+*/
+interface SearchOptions {
+	/**
+	* Search query string (matches against name, domain, path).
+	*/
+	query?: string;
+	/**
+	* Maximum number of results to return.
+	*/
+	limit?: number;
+	/**
+	* Number of results to skip (for pagination).
+	*/
+	offset?: number;
+}
+/**
+* Registry interface - business layer for RXR operations.
+*
+* This interface defines CRUD operations on RXR objects.
+* Different implementations (HostedRegistry, MirrorRegistry, LinkedRegistry)
+* provide different semantics on top of the same Storage layer.
+*/
+interface Registry {
+	/**
+	* Get resource by locator.
+	* @throws RegistryError if not found
+	*/
+	get(rxl: RXL): Promise<RXR>;
+	/**
+	* Store resource.
+	*/
+	put(rxr: RXR): Promise<void>;
+	/**
+	* Check if resource exists.
+	*/
+	has(rxl: RXL): Promise<boolean>;
+	/**
+	* Delete resource.
+	*/
+	remove(rxl: RXL): Promise<void>;
+	/**
+	* List resources matching options.
+	*/
+	list(options?: SearchOptions): Promise<RXL[]>;
+}
+declare class CASRegistry implements Registry {
+	private readonly rxaStore;
+	private readonly rxmStore;
+	constructor(rxaStore: RXAStore, rxmStore: RXMStore);
+	private resolveTag;
+	get(rxl: RXL): Promise<RXR>;
+	put(rxr: RXR): Promise<void>;
+	has(rxl: RXL): Promise<boolean>;
+	remove(rxl: RXL): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL[]>;
+	/**
+	* Clear cached resources (resources with registry).
+	* @param registry - If provided, only clear resources from this registry
 	*/
 	clearCache(registry?: string): Promise<void>;
 	/**
@@ -745,6 +927,45 @@ declare class LinkedRegistry implements Registry {
 	private parsePathToRXL;
 }
 /**
+* Base class for Registry middleware.
+* Delegates all operations to the inner registry.
+* Override specific methods to add custom behavior.
+*/
+declare abstract class RegistryMiddleware implements Registry {
+	protected readonly inner: Registry;
+	constructor(inner: Registry);
+	get(rxl: RXL): Promise<RXR>;
+	put(rxr: RXR): Promise<void>;
+	has(rxl: RXL): Promise<boolean>;
+	remove(rxl: RXL): Promise<void>;
+	list(options?: SearchOptions): Promise<RXL[]>;
+}
+/**
+* Registry validation middleware.
+* Ensures all resources from this registry match the trusted registry.
+*/
+declare class RegistryValidation extends RegistryMiddleware {
+	private readonly trustedRegistry;
+	constructor(inner: Registry, trustedRegistry: string);
+	/**
+	* Validate that manifest registry matches trusted registry.
+	*/
+	private validateRegistry;
+	/**
+	* Get resource and validate registry.
+	*/
+	get(rxl: RXL): Promise<RXR>;
+}
+/**
+* Factory function to create registry validation middleware.
+*
+* @example
+* const registry = withRegistryValidation(hostedRegistry, "deepractice.ai");
+*/
+declare function withRegistryValidation(registry: Registry, trustedRegistry: string): Registry;
+declare const DomainValidation: typeof RegistryValidation;
+declare const withDomainValidation: typeof withRegistryValidation;
+/**
 * Compute SHA-256 digest of data.
 * Returns string in format "sha256:{hex}"
 */
@@ -767,6 +988,7 @@ declare class MemoryRXAStore implements RXAStore {
 }
 declare class MemoryRXMStore implements RXMStore {
 	private readonly manifests;
+	private readonly latestPointers;
 	/**
 	* Build key for manifest lookup.
 	*/
@@ -779,128 +1001,245 @@ declare class MemoryRXMStore implements RXMStore {
 	listNames(registry?: string, query?: string): Promise<string[]>;
 	search(options?: RXMSearchOptions): Promise<StoredRXM[]>;
 	deleteByRegistry(registry: string): Promise<void>;
+	setLatest(name: string, tag: string, registry?: string): Promise<void>;
+	getLatest(name: string, registry?: string): Promise<string | null>;
 	/**
 	* Clear all manifests (for testing).
 	*/
 	clear(): void;
 }
 /**
-* Well-known discovery response format.
+* Isolator type for resolver execution.
+* Matches SandboX isolator types directly.
+* Configured at Registry level, not per-type.
+*
+* - "none": No isolation, fastest (~10ms), for development
+* - "srt": OS-level isolation (~50ms), secure local dev
+* - "cloudflare": Container isolation (~100ms), local Docker or edge
+* - "e2b": MicroVM isolation (~150ms), production (planned)
 */
-interface WellKnownResponse {
-	version?: string;
-	registries: string[];
-}
+type IsolatorType = "none" | "srt" | "cloudflare" | "e2b";
 /**
-* Result from discoverRegistry().
+* ResolveContext - Pure data context passed to resolver in sandbox.
+*
+* This is a serializable data structure that replaces RXR for sandbox execution.
+* The executor pre-processes RXR (extracts files) before passing to resolver.
 */
-interface DiscoveryResult {
-	domain: string;
-	registries: string[];
+interface ResolveContext {
+	/**
+	* Resource manifest metadata.
+	*/
+	manifest: {
+		domain: string
+		path?: string
+		name: string
+		type: string
+		version: string
+	};
+	/**
+	* Extracted files from archive.
+	* Key is file path, value is file content as Uint8Array.
+	*/
+	files: Record<string, Uint8Array>;
 }
 /**
-* Discover registry for a domain using well-known.
-* @param domain - The domain to discover (e.g., "deepractice.ai")
-* @returns Discovery result with domain and authorized registries
+* BundledType - Pre-bundled resource type ready for execution.
+* Contains bundled code string instead of closure.
+*
+* Note: Sandbox isolation is configured at Registry level via createRegistry({ sandbox: ... })
 */
-declare function discoverRegistry(domain: string): Promise<DiscoveryResult>;
+interface BundledType {
+	/**
+	* Type name (e.g., "text", "json", "prompt").
+	*/
+	name: string;
+	/**
+	* Alternative names for this type.
+	*/
+	aliases?: string[];
+	/**
+	* Human-readable description.
+	*/
+	description: string;
+	/**
+	* JSON Schema for resolver arguments.
+	*/
+	schema?: JSONSchema;
+	/**
+	* Bundled resolver code (executable in sandbox).
+	*/
+	code: string;
+}
 /**
-* Registry-specific error.
+* JSON Schema property definition.
 */
-declare class RegistryError extends ResourceXError {
-	constructor(message: string, options?: ErrorOptions);
+interface JSONSchemaProperty {
+	type: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+	description?: string;
+	default?: unknown;
+	enum?: unknown[];
+	items?: JSONSchemaProperty;
+	properties?: Record<string, JSONSchemaProperty>;
+	required?: string[];
 }
 /**
-* Base class for Registry middleware.
-* Delegates all operations to the inner registry.
-* Override specific methods to add custom behavior.
+* JSON Schema definition for resolver arguments.
+* Used by UI to render parameter forms.
 */
-declare abstract class RegistryMiddleware implements Registry {
-	protected readonly inner: Registry;
-	constructor(inner: Registry);
-	get(rxl: RXL): Promise<RXR>;
-	put(rxr: RXR): Promise<void>;
-	has(rxl: RXL): Promise<boolean>;
-	remove(rxl: RXL): Promise<void>;
-	list(options?: SearchOptions): Promise<RXL[]>;
+interface JSONSchema extends JSONSchemaProperty {
+	$schema?: string;
+	title?: string;
 }
 /**
-* Registry validation middleware.
-* Ensures all resources from this registry match the trusted registry.
+* ResolvedResource - Structured result object returned by resolver.
+* Contains execute function, original resource, and optional schema for UI rendering.
 */
-declare class RegistryValidation extends RegistryMiddleware {
-	private readonly trustedRegistry;
-	constructor(inner: Registry, trustedRegistry: string);
+interface ResolvedResource<
+	TArgs = void,
+	TResult = unknown
+> {
 	/**
-	* Validate that manifest registry matches trusted registry.
+	* Original resource object (RXR from @resourcexjs/core).
 	*/
-	private validateRegistry;
+	resource: unknown;
 	/**
-	* Get resource and validate registry.
+	* Execute function to get the resource content.
+	* - For static resources (text/json/binary): call with no arguments
+	* - For dynamic resources (tool): call with arguments
 	*/
-	get(rxl: RXL): Promise<RXR>;
+	execute: (args?: TArgs) => TResult | Promise<TResult>;
+	/**
+	* JSON Schema for the arguments (undefined if no arguments needed).
+	* UI uses this to render parameter forms.
+	*/
+	schema: TArgs extends void ? undefined : JSONSchema;
 }
 /**
-* Factory function to create registry validation middleware.
-*
-* @example
-* const registry = withRegistryValidation(hostedRegistry, "deepractice.ai");
+* ResourceResolver - Transforms resource into a structured result object.
+* The execute function is lazy-loaded: content is only read when called.
 */
-declare function withRegistryValidation(registry: Registry, trustedRegistry: string): Registry;
-declare const DomainValidation: typeof RegistryValidation;
-declare const withDomainValidation: typeof withRegistryValidation;
+interface ResourceResolver<
+	TArgs = void,
+	TResult = unknown
+> {
+	/**
+	* JSON Schema for arguments (required if TArgs is not void).
+	* This constraint ensures type safety at definition time.
+	*/
+	schema: TArgs extends void ? undefined : JSONSchema;
+	/**
+	* Resolve resource into a structured result object.
+	* @param rxr - RXR object from @resourcexjs/core
+	*/
+	resolve(rxr: unknown): Promise<ResolvedResource<TArgs, TResult>>;
+}
 /**
-* Provider configuration passed to createStores/createLoader.
+* ResourceType - Defines how a resource type is handled.
 */
-interface ProviderConfig {
+interface ResourceType<
+	TArgs = void,
+	TResult = unknown
+> {
 	/**
-	* Base path for storage (filesystem) or connection info.
+	* Type name (e.g., "text", "json", "binary").
 	*/
-	path?: string;
+	name: string;
 	/**
-	* Platform-specific configuration.
+	* Alternative names for this type (e.g., ["txt", "plaintext"]).
 	*/
-	[key: string]: unknown;
+	aliases?: string[];
+	/**
+	* Human-readable description.
+	*/
+	description: string;
+	/**
+	* Resolver to transform RXR into structured result object.
+	*/
+	resolver: ResourceResolver<TArgs, TResult>;
 }
 /**
-* Stores created by the provider.
+* Plain text content
 */
-interface ProviderStores {
-	rxaStore: RXAStore;
-	rxmStore: RXMStore;
+declare const textType: BundledType;
+/**
+* JSON content
+*/
+declare const jsonType: BundledType;
+/**
+* Binary content
+*/
+declare const binaryType: BundledType;
+/**
+* All built-in types as an array.
+*/
+declare const builtinTypes: BundledType[];
+/**
+* Bundle a resource type from a source file.
+*
+* @param sourcePath - Path to the .type.ts file
+* @param basePath - Base path for resolving relative paths (defaults to cwd)
+* @returns BundledType ready for registry
+*
+* @example
+* ```typescript
+* const promptType = await bundleResourceType("./prompt.type.ts");
+* ```
+*/
+declare function bundleResourceType(sourcePath: string, basePath?: string): Promise<BundledType>;
+/**
+* Resource type related error.
+*/
+declare class ResourceTypeError extends ResourceXError {
+	constructor(message: string);
 }
 /**
-* Resource loader interface for loading from directories/archives.
+* TypeHandlerChain - Manages resource type registration.
+*
+* Responsibilities:
+* - Register types (name + aliases)
+* - Look up types by name
+*
+* Execution is delegated to ResolverExecutor (in registry package).
+*
+* Built-in types (text, json, binary) are registered by default.
 */
-interface ResourceLoader2 {
+declare class TypeHandlerChain {
+	private handlers;
+	private constructor();
 	/**
-	* Check if this loader can handle the given source.
+	* Create a new TypeHandlerChain instance.
+	* Built-in types (text, json, binary) are included by default.
 	*/
-	canLoad(source: string): boolean | Promise<boolean>;
+	static create(): TypeHandlerChain;
 	/**
-	* Load resource from source.
+	* Internal registration (no duplicate check).
 	*/
-	load(source: string): Promise<unknown>;
-}
-/**
-* ResourceX Provider - Platform implementation interface.
-*
-* Platforms implement this interface to provide storage and loading
-* capabilities for their environment.
-*/
-interface ResourceXProvider {
+	private registerInternal;
 	/**
-	* Platform identifier.
+	* Register a type.
+	* @throws ResourceTypeError if type is already registered
 	*/
-	readonly platform: string;
+	register(type: BundledType): void;
 	/**
-	* Create storage instances for the platform.
+	* Check if a type is supported.
 	*/
-	createStores(config: ProviderConfig): ProviderStores;
+	canHandle(typeName: string): boolean;
 	/**
-	* Create resource loader (optional).
-	* Not all platforms support loading from filesystem.
+	* Get handler for a type.
+	* @throws ResourceTypeError if type is not supported
 	*/
-	createLoader?(config: ProviderConfig): ResourceLoader2;
+	getHandler(typeName: string): BundledType;
+	/**
+	* Get handler for a type, or undefined if not found.
+	*/
+	getHandlerOrUndefined(typeName: string): BundledType | undefined;
+	/**
+	* Get all supported type names (including aliases).
+	*/
+	getSupportedTypes(): string[];
+	/**
+	* Clear all registered types (for testing).
+	*/
+	clear(): void;
 }
-export { wrap, withDomainValidation, textType, resource, parse, manifest, locate, loadResource, jsonType, isValidDigest, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, StoredRXM, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResolvedResource, ResolveContext, RegistryMiddleware, RegistryError, Registry, RXR, RXMStore, RXMSearchOptions, RXM, RXL, RXD, RXAStore, RXA, ProviderStores, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, FolderLoader, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };
+export { wrap, withDomainValidation, textType, resource, resolveSource, parse, manifest, locate, loadResource, jsonType, isValidDigest, generateDefinition, format, extract, discoverRegistry, define, computeDigest, bundleResourceType, builtinTypes, binaryType, archive, WellKnownResponse, TypeHandlerChain, TypeDetectorChain, TypeDetector, TypeDetectionResult, StoredRXM, SourceLoaderChain, SourceLoader, SkillDetector, SearchOptions, ResourceXProvider, ResourceXError, ResourceTypeError, ResourceType, ResourceResolver, ResourceLoader, ResourceJsonDetector, ResolvedResource, ResolveSourceConfig, ResolveContext, RegistryMiddleware, RegistryError, Registry, RXS, RXR, RXMStore, RXMSource, RXMSearchOptions, RXMDefinition, RXMArchive, RXM, RXL, RXD, RXAStore, RXA, ProviderStores, ProviderConfig, MemoryRXMStore, MemoryRXAStore, ManifestError, LocatorError, LoadResourceConfig, LinkedRegistry, JSONSchemaProperty, JSONSchema, IsolatorType, GitHubSourceLoader, FolderSourceLoader, FolderLoader, FileTree, FileEntry, DomainValidation, DiscoveryResult, DefinitionError, ContentError, CASRegistry, BundledType };