ARP Protocol Concept Design: ARP/ARL/ARI Three-Layer Architecture

[deepracticexs]

Overview

This issue documents the three-layer conceptual architecture for the Agent Resource Protocol (ARP), clarifying the relationship between ARP, ARL, and ARI.

Concept Hierarchy

ARP - Protocol Family

The umbrella term for the entire Agent Resource Protocol specification, encompassing multiple concrete forms.

ARL - Agent Resource Locator (Complete Form)

Format: `arp:{semantic}:{transport}://{location}`

Purpose: Fully specify semantic type, transport protocol, and resource location.

Examples:

• `arp:tool:https://cdn.com/tool.wasm\`
• `arp:dpml:arr://deepractice@assistant`
• `arp:prompt:file://./local/prompt.txt`
• `arp:data:git://github.com/org/repo#main`

Use Cases:

• Development (local file references)
• Direct CDN/HTTPS resources
• Explicit transport specification required

ARI - Agent Resource Identifier (Simplified Form)

Format: `arp:{semantic}://{org}@{name}`

Purpose: Reference resources by name only, with transport defaulting to registry resolution.

Examples:

• `arp:tool://myorg@web-search`
• `arp:prompt://deepractice@assistant`
• `arp:dpml://system@default`

Use Cases:

• Production deployments (managed through registry)
• Version-agnostic references
• Centralized resource management

Resolution Flow

```
ARI → (Registry Resolution) → ARL

arp:tool://myorg@web-search
↓ (Query registry)
arp:tool:https://cdn.myorg.com/tools/web-search.wasm
```

Interface Design

```typescript
// Base protocol interface
interface AgentResourceProtocol {
protocol: "arp"
semantic: string
}

// ARL - Complete locator form
interface AgentResourceLocator extends AgentResourceProtocol {
transport: string
location: string
}

// ARI - Identifier form
interface AgentResourceIdentifier extends AgentResourceProtocol {
org?: string
name: string
// transport implicitly defaults to registry
}

// Type guards
function isARL(arp: AgentResourceProtocol): arp is AgentResourceLocator {
return 'transport' in arp && 'location' in arp
}

function isARI(arp: AgentResourceProtocol): arp is AgentResourceIdentifier {
return 'name' in arp
}
```

Usage Scenarios

Development Workflow

```yaml

Development: Direct file reference (ARL)

dev:

• arp:tool:file://./dev/my-tool.js
• arp:prompt:file://./prompts/test.txt

Testing: CDN reference (ARL)

test:

• arp:tool:https://test-cdn.com/my-tool.wasm

Production: Registry reference (ARI)

prod:

• arp:tool://myorg@my-tool
• arp:prompt://myorg@production-prompt
  ```

Version Management

```yaml

ARL - Locked to specific location/version

resources:

• arp:tool:https://cdn.com/tool-v2.0.wasm

ARI - Version managed by registry

resources:

• arp:tool://myorg@tool # Registry resolves to latest compatible version
  ```

Benefits

1. Conceptual Clarity

   • ARP = Protocol family
   • ARL = Explicit, complete form
   • ARI = Simplified, registry-managed form

2. Flexibility

   • Choose ARL when you need explicit control
   • Choose ARI when you want registry management

3. Smooth Transition

   • Develop with ARL (file://)
   • Test with ARL (https://)
   • Deploy with ARI (registry)

Next Steps

• Implement parser to distinguish ARL vs ARI formats
• Define registry resolution API for ARI
• Update RFC to document ARL/ARI concepts
• Create examples for both forms

Related Issues

• ARP RFC v1.0.0 Draft Complete #6 ARP RFC v1.0.0 Draft

[deepracticexs]

Parser Design Specification Added

Based on our design discussion, I've created a comprehensive parser design specification. Here are the key decisions:

Core Design Principles

1. ARI is syntactic sugar for ARL: ARI is not a separate type but a convenience syntax that defaults to transport: 'registry'

2. Field naming:

   • protocol: Always 'arp'
   • semantic: Resource semantic type (not just category, but defines the entire processing chain)
   • transport: How to access the resource
   • location: Raw location string (format depends on transport)

3. Registry location format: [org@]name[#version][@digest]

   • @ for org/namespace (npm convention)
   • # for version/tag (git fragment convention)
   • @ for digest after version (docker convention)

4. Error handling strategy:

   • Library layer: Throw exceptions (simple, composable)
   • Application layer: Result pattern (safe, production-ready)

5. Parser scope: Only handles parsing and format validation, NOT resource loading, downloading, or registry resolution

Implementation Checklist

• Implement core parseARP function
• Implement error classes and codes
• Write comprehensive unit tests
• Implement parseARPSafe wrapper
• Document public API with JSDoc
• Add TypeScript type tests

Full specification document available at: /home/sean/deepractice/parser-design.md

Key Specification Sections

1. Data Model: ARL interface with protocol, semantic, transport, location fields
2. Parsing Rules: Algorithm for both ARL (explicit transport) and ARI (implicit registry) formats
3. Registry Location Format: Detailed breakdown of [org@]name[#version][@digest] syntax
4. Error Handling: ARPError hierarchy with specific error codes
5. Package Structure: Clear separation between @darp/parser (library) and @darp/core (application)
6. Examples: Comprehensive valid and error case examples
7. Future Extensions: Transport handler registry, semantic handler registry, parser configuration

The specification is ready for implementation. Please review and provide feedback if any adjustments are needed.