Identity, Slug, and Key Helpers

Core identity helpers produce predictable identifiers for public URLs, machine keys, admin handles, and UUID-backed fallback values. Addons should call them before persisting a record or exposing a route.

Owners

• `core/identity/uuid.php` owns v4 UUID generation, validation, normalization, and UUID fragments.
• `core/identity/slug.php` owns public slug normalization, slug validation, UUID-fragment slug fallback, and safe slug candidate parsing.
• `core/identity/identity.php` owns higher-level public slug, machine key, admin handle, uniqueness, and manual-value preservation helpers.

Common Calls

• `amv_core_uuid_generate()` returns a canonical v4 UUID.
• `amv_core_slug_normalize($title)` turns display text into a URL-safe slug candidate.
• `amv_core_slug_with_uuidfrag($title, $uuid, 'page')` appends the canonical 4-character UUID fragment when a stable generated handle is needed.
• `amv_core_identity_public_slug($title, $uuid, 'page')` builds a public slug with a fallback.
• `amv_core_identity_machine_key($label, 'addon')` builds underscore-delimited keys for manifests, internal handles, and settings.
• `amv_core_identity_unique_value($candidate, $exists, ['maxLength' => 96])` resolves collisions without each addon writing its own suffix loop.

Existing Usage

• Wiki pulls these helpers from `addons/wiki/src/runtime.php` and uses `amv_wiki_slug()`, `amv_wiki_key()`, and `amv_wiki_space_key()` as addon-local adapters around Core.
• Wiki smoke coverage checks UUID-fragment page slugs in `addons/wiki/tests/smoke.php`.
• Integration smoke requires identity and slug rails before route checks in `tools/integration_smoke.php`.

Example Pattern

When saving a public record, generate the UUID first, derive the slug from the title, preserve a valid manual slug if one was submitted, then call `amv_core_identity_unique_value()` against the table/column lookup. Store the UUID and slug together so future route and menu target records can resolve by stable UUID while showing readable URLs.

Do Not Duplicate

• Do not use ad hoc `strtolower()` plus regex slug code inside addons.
• Do not use random short strings as primary identity.
• Do not append full UUIDs to public slugs when the shared UUID-fragment helpers already define the platform convention.

UUID Version Rule

Amvionlie platform UUIDs must be canonical version-4 UUIDs. Use amv_core_uuid_generate(), amv_core_uuid_generate_v4(), and amv_core_uuid_is_valid() for platform identity values.

Amvionlie-owned code, in-house scripts, install seeds, repair scripts, documentation sync scripts, and migrations must not use database-native UUID generators such as MySQL UUID() for Amvionlie platform record identifiers. MySQL UUID() may produce UUID versions that fail Amvionlie admin validators. A row inserted this way can exist in the database but still fail Admin edit, lookup, mutation, or route flows that validate UUIDs before querying.

Third-party developers are strongly recommended to use the Amvionlie Core UUID helpers for any identifier that will be stored in Amvionlie-owned tables, passed through Amvionlie admin routes, declared in addon contracts, or validated by Amvionlie APIs. Amvionlie cannot control every private identifier a third-party addon uses internally. However, any identifier that crosses into Amvionlie platform contracts must satisfy the platform canonical v4 UUID validation.