Human-readable URI system in haih-agent maintains address stability and SEO signals
Human-readable URI system in haih-agent maintains address stability and SEO signals
In haih-agent, public Concepts are gradually transitioning from technical addresses with identifiers to human-readable addresses (ChPU / friendly URLs) that reflect the page's meaning.
This implementation began shaping in the commit:
https://github.com/haih-net/agent/commit/1f99a51dd407eb4e58f9e2f83f411a265db2f24c
URI Generation
If a URI is not explicitly defined, a human-readable slug built from the name is used for the Concept. The common slugifyUri() logic handles this.
The URI is processed segment by segment, rather than as a single string. This is important: / remains the route structure, while each individual segment is normalized independently.
Example:
/concepts/TypeScript Generics
→
/concepts/typescript-generics
This approach allows using semantic words directly in the URL instead of a technical CUID.
URI Changes and 301
When changing a URI, the common processUriChange(oldUri, newUri) logic or its current equivalent is used.
The new URI is normalized first. If the address has actually changed, the system creates a permanent redirect:
old URI → new URI
HTTP 301
After that, the Concept retains the new address.
This allows changing and improving URIs without mass destruction of already published links.
Decoding Incoming URLs
When reading a route, percent-encoded URLs must be brought to the same representation in which the URI is stored in the system.
Initially, the issue manifested in addresses with %22 and other encoded characters. Simply using decodeURI() solved some cases, but proved insufficient for reserved characters.
For example:
/projects/%40prisma-cms/sendmail
must match:
/projects/@prisma-cms/sendmail
decodeURI() does not convert %40 to @, so the target logic must be segment-aware: first preserve the pathname structure by /, then decode individual segments via decodeURIComponent(), and reassemble the path.
This is symmetrical to the slugifyUri() logic, which also operates segment by segment.
Migrating Old Concepts
The new URI mechanism itself does not fix historical Concepts that were already created with technical URLs. An administrative bulk migration mechanism is needed for this: compute the current slug, update the URI via the common address-changing logic, and save a 301 from the old URL.
Related mass URI update work is being developed separately in haih-agent.
SEO Significance
The system solves several tasks at once:
- The URL itself contains the document topic and becomes an additional semantic signal;
- Old links do not turn into 404s after address improvements;
- 301 helps transfer accumulated signals to the new canonical URI;
- Technical CUIDs gradually cease to be the public interface of the site;
- Unified URI normalization reduces the number of false duplicates and 404s;
- Downstream projects on haih-agent get a common human-readable URL mechanism instead of local implementations.
This system is especially important for fi1osof.ru — the unified information core of professional activity, where public Concepts must have clear addresses and stable internal linking.
Current Limitation: Link Integrity Within Content
The stable URI of the entity itself does not yet guarantee the integrity of the entire graph. Concept content may still contain links to non-existent or already modified URIs.
Therefore, the next necessary layer of the system is automatic validation of internal links and updating content upon Concept creation/modification. This should prevent broken links in AI-generated and manually updated content.
Related: