runid

Run-ID template engine for Vulcan.

A run_id is the per-write identifier carried on every row of a Vulcan shard. Templates are ordinary Python format strings with {name} placeholders; an additional {name?} form marks an optional placeholder that falls back to "na" when the substitution is not provided.

The rendered string must satisfy stringforge.vacuavault.schema.LABEL_SLUG_RE, so a Vulcan run_id is admissible as a vault label after future promotion. The constraints are: the first character must be in [A-Za-z0-9]; subsequent characters must be in [A-Za-z0-9_-]; and an optional trailing _v\d+ version suffix is permitted. Substitution values are coerced via _slugify() before insertion. Note that _slugify() strips leading and trailing - but does not strip a leading _, so a substitution rendering with a leading _ will fail validation.

stringforge.vulcan.runid.OPTIONAL_PLACEHOLDER_FALLBACK: str = 'na'

Sentinel used to render an optional placeholder when no value is available. Chosen to be slug-safe and visually distinct.

stringforge.vulcan.runid.render(template=None, *, project='', now=None, **substitutions)

Render a Vulcan run_id from a template and a set of substitutions.

The rendered identifier is guaranteed to satisfy stringforge.vacuavault.schema.LABEL_SLUG_RE so it is admissible as a vault label after a future promotion step. Non slug-safe substitution values are coerced via _slugify() before insertion; trailing whitespace and disallowed punctuation collapse into single dashes.

Parameters:

• template (Union[str, Callable[..., str], None]) –

  • str – format string with {name} and/or {name?} placeholders. Plain identifiers only; attribute access ({x.y}) and item access ({x[0]}) are rejected.

  • Callable – invoked with **substitutions; the returned string is used verbatim and must satisfy LABEL_SLUG_RE.

  • None – fall back to uuid.uuid4()’s .hex.

• project (str) – Default value for {project} when not present in substitutions.

• now (Optional[datetime]) – Override the wall-clock for tests. Defaults to datetime.datetime.now() in UTC.

• **substitutions (Any) – Values to interpolate. Standard keys include h11, h12, ks_id, triang_id, conifold_id, cicy_id, seed, solver. Unknown keys are forwarded to the template engine.

Returns:

str – A slug-safe run identifier.

Raises:

• KeyError – A required (non-?) placeholder is unsupplied.

• ValueError – The rendered string is not a valid run_id, or the template uses attribute / item access.

Return type:

str