Module id 

Entity ID parsing, generation, and path mapping.

Structs

SlugDerivation

A strict-gate derivation result: the slug plus the distinct title characters (source order, post NFC + case-fold) the pipeline dropped on the way. dropped_chars non-empty means the title and its id diverge beyond case/whitespace — the mutation surfaces it as the typed TITLE_CHARS_DROPPED_FROM_SLUG warning so the divergence stays visible without being fatal.

Enums

SlugError

Error cases for title→slug derivation. title_to_slug itself is total — any title produces a slug (residual cases like all-emoji collapse to a deterministic short-hash id) — so it never returns these variants directly. The strict mutation-entry gate validate_and_derive_slug returns them for control characters and for input that would have fallen back to the hash slug; enforce_id_length returns Self::IdTooLong when the derived mem--slug exceeds the read-path length cap.

WikiLinkError

Strict wiki-link grammar refusal. Returned by wiki_link_to_id when the input between [[...]] (after alias / .md strip) does not resolve to a slug-form EntityId. Two variants matching the two grammars a wiki-link target carries:

Constants

ENTITY_ID_MAX_LEN

Cap on the full mem--slug entity id (Unicode scalar length). 200 leaves headroom for mem---style prefixes and the .md suffix against the 255-byte NAME_MAX ceiling on common filesystems. The read-path validator on the MCP surface and the write-path slug derivation share this constant so an entity that the write side accepts is always readable on the same wire. F2 + F4.

TITLE_GRAMMAR_RULE

The accepted title grammar, stated as a rule. THE single sentence every surface that documents titles carries: the CLI’s create/rename help embeds it at build time, the MCP memstead_create / memstead_rename descriptions contain it verbatim (a tool-surface test asserts the containment), and the handbook quotes it naming this constant as its source. A conformance test in this module asserts validate_and_derive_slug’s behaviour matches the sentence’s claim — so neither the prose nor the validator can drift alone.

Functions

build_id

The separator between mem and entity path in IDs. Build an EntityId from mem and title.

enforce_id_length

Reject ids whose Unicode scalar length exceeds ENTITY_ID_MAX_LEN. Shared by build_id and the engine’s create_entity / rename_entity paths so the write side never produces an id the read side would refuse. The cap is on the composed <mem>--<slug> id (which is also the filename), so the error echoes the id itself — the reason, the echoed input, and the reported length all describe the id, not the title. F2 + F4.

file_path_to_id

Convert a relative file path to a mem-prefixed entity ID.

id_to_file_path

Compute the file path for an entity given its ID and base directory. The path is relative to the mem directory.

title_to_slug

Convert a title string to a kebab-case slug.

validate_and_derive_slug

Strict slug derivation for mutation entry (memstead_create, memstead_rename). Runs the same pipeline as title_to_slug — byte-identical slugs for every title — but refuses the residual cases the permissive variant tolerates:

validate_id_path_grammar

Validate that an EntityId’s path matches the wiki-link grammar (^[\p{Ll}\p{Lo}\p{Lm}\p{N}-]+(/[\p{Ll}\p{Lo}\p{Lm}\p{N}-]+)*$). Same regex the strict ingress validator applies to inline [[...]] targets — keeping the two gates aligned ensures the relate-target path doesn’t admit ids that would fail an in-body wiki-link parse.

validate_mem_name_grammar

Validate a mem name (left side of --). Hierarchical paths are first-class: mem names accept <segment>(/<segment>)* where each segment matches the single-segment rule ([a-z0-9-]+). Leading slashes, trailing slashes, double slashes, and any character outside the allowed segment alphabet are explicit refusals.

validate_rel_type

Validate relationship type. Input is case-insensitive and canonicalised to uppercase; only ASCII letters and underscores are permitted.

wiki_link_to_id

Convert a wiki-link target to a mem-prefixed entity ID, refusing non-slug-form inputs.

wiki_link_to_id_lenient

Permissive wiki-link decoder for read-side scanners that must tolerate pre-strict-gate on-disk drift (e.g. dangling-link reporters, body-link scanners on stored entities, archive readers for non-canonical sources). Returns an EntityId even for non-slug-form input — non-conformant chars flow through unchanged. Mutation paths MUST NOT use this helper; they use wiki_link_to_id and propagate the typed refusal.