Add deterministic contribution IDs and stack lookup IDs for resolved artifacts

docs/reference/presets.md

@@ -205,6 +205,25 @@ specify preset add team-workflow --priority 10
 
 For any file that both provide, `compliance` wins (priority 5 < 10). For files only one provides, that one is used. For files neither provides, the core default is used.
 
+## Contribution Identifiers
+
+Every command, template, and script contributed by a preset (or an extension, or the core layer) is addressable at read time by a deterministic opaque identifier of the form:
+
+```text
+{layer}:{sourceId}:{kind}:{name}
+```
+
+- `layer` is one of `core`, `preset`, or `extension`.
+- `sourceId` is `_` for `core`, the preset pack id for `preset`, or the extension id for `extension`.
+- `kind` is one of `command`, `template`, or `script`.
+- `name` is the entry's declared `name` field.
+
+Identifiers are computed on demand from author-declared manifest content and are never persisted to `.specify/` or any cache. Copying a preset to another machine (or touching its files) does not change the identifiers it produces.
+
+`PresetResolver.collect_all_layers()` returns layer dicts that each include a `lookupId` field pointing back to the originating contribution's `id`. Project-local overrides in `.specify/templates/overrides/` are a resolver-only concept — they carry a synthetic `project:_:{kind}:{name}` `lookupId` that intentionally does not match any manifest contribution.
+
+For the full grammar, including the hook name-component convention and the discriminator recipe used by extensions, see the [Extension API Reference — Contribution Identifiers](../../extensions/EXTENSION-API-REFERENCE.md#contribution-identifiers) section.
+
 ## FAQ
 
 ### Can I use multiple presets at the same time?

extensions/EXTENSION-API-REFERENCE.md

@@ -10,6 +10,7 @@ Technical reference for Spec Kit extension system APIs and manifest schema.
 4. [Configuration Schema](#configuration-schema)
 5. [Hook System](#hook-system)
 6. [CLI Commands](#cli-commands)
+7. [Contribution Identifiers](#contribution-identifiers)
 
 ---
 
@@ -859,7 +860,60 @@ satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # bool
 
 ---
 
-## File System Layout
+## Contribution Identifiers
+
+Every command, template, script, and hook contributed by an extension (or a preset, or the core layer) is addressable at read time by a deterministic opaque identifier. Resolved artifact-stack layers carry a matching `lookupId` field that points back to the contribution the layer came from. Identifiers are **computed on demand from author-declared manifest content** and are **never persisted** to `.specify/` or to any cache file.
+
+### Grammar
+
+Named contributions (commands, templates, scripts) follow:
+
+```text
+{layer}:{sourceId}:{kind}:{name}
+```
+
+- `layer` is one of `core`, `preset`, or `extension`.
+- `sourceId` is `_` for `core`, the preset pack id for `preset`, or the extension id for `extension`.
+- `kind` is one of `command`, `template`, `script`, or `hook`.
+- `name` is the contribution's declared `name` field.
+
+Hook contributions use a compound name-component built from the event and command:
+
+```text
+{layer}:{sourceId}:hook:{eventName}:{command}
+```
+
+When two or more hook entries within the same source share the same `(eventName, command)` pair, a 12-hex-character discriminator is appended:
+
+```text
+{layer}:{sourceId}:hook:{eventName}:{command}:{discriminator}
+```
+
+The discriminator is the first 12 lowercase hex characters of `sha256(canonical_json(entry - {eventName, command}))`. Two hook entries with byte-identical declared fields (after removing `eventName` and `command`) are rejected at manifest load with a `ValidationError` naming both positions — there is no meaningful way to distinguish them at read time.
+
+### Reserved character
+
+`:` is reserved as the identifier component separator. It cannot appear inside any of `layer`, `sourceId`, `kind`, `name`, `eventName`, or `command`. Extension ids, command names, template names, and script names are already constrained by their existing regex patterns (`^[a-z0-9-]+$` and friends), which forbid `:`. Hook event names (mapping keys) and hook `command` values are additionally validated to reject `:` at manifest load.
+
+### The `project:` sentinel
+
+Project-local overrides in `.specify/templates/overrides/` are a resolver-only concept — they have no backing manifest and cannot appear in `iter_contributions()`. Layers of that kind carry a synthetic `lookupId` of the form `project:_:{kind}:{name}` so consumers that reverse-lookup the id always see "not found", which is the intended behaviour: overrides are addressable at the stack level, not as first-class contributions.
+
+### Python API
+
+`ExtensionManifest.iter_contributions()` yields dicts of the form `{layer, sourceId, kind, name, id, ...author-declared fields}`; each entry's `id` is the computed identifier. `ExtensionManifest.contribution_id(kind, name)` returns the id for a single lookup, or `None` if no contribution matches. `PresetManifest` exposes the same two methods.
+
+`PresetResolver.collect_all_layers()` returns layer dicts that include a `lookupId` field for every layer type (`project override`, preset, extension, core, and bundled core).
+
+### Determinism guarantees
+
+Identifier derivation reads only the in-memory declared manifest content. No filesystem paths, no `os.environ`, no timestamps, and no file-content hashes contribute to any id. Copying an extension or preset to a different machine (or renaming its directory, or touching its files) does not change the identifiers it produces.
+
+### Opacity guidance
+
+Identifiers are stable, but treat them as **opaque strings** in stored data (registries, cache files, external tooling). Parse them with the helpers in `specify_cli._identifier` (`derive_named_id`, `derive_hook_id`) rather than by string-splitting on `:` — the discriminator suffix and future grammar extensions may otherwise catch you out.
+
+
 
 ```text
 .specify/

src/specify_cli/_identifier.py

@@ -0,0 +1,178 @@
+"""Deterministic identifiers for Spec Kit contributions and resolved stack layers.
+
+Every command, template, script, and hook contribution surfaced by a preset or
+extension manifest carries a computed opaque ``id`` string, and every layer of a
+resolved artifact stack carries a matching ``lookupId``. The identifier value is
+derived only from author-declared manifest data — it never depends on file
+contents, timestamps, archive hashes, installation directory paths, install-time
+random values, or list positions. That is what makes identifiers portable
+across machines, project locations, and reinstalls, and what lets consumers use
+them as stable join keys.
+
+Grammar for named contributions (commands, templates, scripts)::
+
+    id = "{layer}:{sourceId}:{kind}:{name}"
+
+    layer    ∈ {"core", "preset", "extension"}
+    sourceId = "_" when layer == "core"; the preset id or extension id otherwise
+    kind     ∈ {"command", "template", "script", "hook"}
+    name     = the contribution's declared ``name``
+
+Hook identifiers use ``{eventName}:{command}`` as the name component::
+
+    id = "{layer}:{sourceId}:hook:{eventName}:{command}[:{discriminator}]"
+
+The 12-lowercase-hex discriminator is appended only when at least one sibling
+hook in the same source shares the same ``(eventName, command)`` pair, and it is
+computed by SHA-256 of a canonical JSON serialization of the hook entry's
+declared fields (with ``eventName`` and ``command`` removed, since they already
+appear in the identifier prefix). Two hook entries in the same source whose
+declared fields produce byte-identical canonical JSON are rejected at manifest
+load time — they are semantically identical listeners.
+
+The functions in this module are pure — inputs are strings or in-memory
+mappings parsed from a manifest, outputs are strings. None of them read from
+disk, look at ``os.environ``, call ``datetime``, or hash file contents. That
+guarantee is what preserves portability, and it is enforced by inspection
+rather than by runtime checks: any change here that adds an ambient input is a
+change that breaks the identifier contract.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Iterable, Mapping
+
+
+PROJECT_OVERRIDE_LAYER = "project"
+"""Resolver-only layer label for project-local override layers.
+
+Project overrides are a resolver feature — they are not backed by any manifest
+contribution. When a resolved artifact stack contains a project-override layer,
+its ``lookupId`` uses this label so the round-trip invariant (every layer
+carries a ``lookupId``) still holds. No manifest ``iter_contributions()`` will
+ever emit a matching ``id``, so consumers see "not found" for the lookup, which
+is the correct outcome for a layer with no originating manifest entry.
+"""
+
+_DISCRIMINATOR_LENGTH = 12
+
+
+class IdentifierComponentError(ValueError):
+    """Raised when a manifest component would break identifier grammar."""
+
+
+def validate_component(value: Any, field_label: str) -> str:
+    """Return ``value`` unchanged if it is a non-empty ``:``-free string.
+
+    Manifest components that appear in an identifier (``layer``, ``sourceId``,
+    ``kind``, ``name``, ``eventName``, ``command``) may not contain the ``:``
+    delimiter — the grammar has no escape rule. This function is the guard used
+    by manifest validators to reject offending values at load time with a clear
+    message naming the field.
+    """
+    if not isinstance(value, str):
+        raise IdentifierComponentError(
+            f"Invalid {field_label}: expected a string, got {type(value).__name__}"
+        )
+    if not value:
+        raise IdentifierComponentError(
+            f"Invalid {field_label}: value must not be empty"
+        )
+    if ":" in value:
+        raise IdentifierComponentError(
+            f"Invalid {field_label} '{value}': ':' is reserved as an identifier delimiter"
+        )
+    return value
+
+
+def derive_named_id(layer: str, source_id: str, kind: str, name: str) -> str:
+    """Build the identifier string for a named contribution kind.
+
+    Callers are expected to have already validated each component with
+    :func:`validate_component` at manifest-load time; this function does not
+    revalidate — it is a pure string join so the identifier can be computed
+    cheaply on every read.
+    """
+    return f"{layer}:{source_id}:{kind}:{name}"
+
+
+def canonical_json(value: Any) -> bytes:
+    """Serialize ``value`` to a canonical UTF-8 JSON byte string.
+
+    Mapping keys are sorted lexicographically at every depth, list order is
+    preserved (author intent), whitespace is stripped, and non-ASCII characters
+    are emitted verbatim. This is the byte string that the hook discriminator
+    hashes and that the manifest loader uses to detect byte-identical duplicate
+    hook entries.
+    """
+    normalized = _normalize_for_canonical_json(value)
+    return json.dumps(
+        normalized,
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _normalize_for_canonical_json(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {str(k): _normalize_for_canonical_json(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_normalize_for_canonical_json(v) for v in value]
+    return value
+
+
+def _has_hook_sibling_collision(
+    event_name: str,
+    command: str,
+    siblings: Iterable[Mapping[str, Any]],
+) -> bool:
+    """Return True when at least one sibling shares the same event/command pair.
+
+    ``siblings`` is the full same-source hook entry list including the entry
+    whose identifier is being derived. A collision therefore means at least two
+    entries share the pair.
+    """
+    seen = 0
+    for entry in siblings:
+        if entry.get("eventName") == event_name and entry.get("command") == command:
+            seen += 1
+            if seen >= 2:
+                return True
+    return False
+
+
+def hook_discriminator(declared_fields: Mapping[str, Any]) -> str:
+    """Compute the 12-hex-char SHA-256 discriminator for a hook entry.
+
+    ``declared_fields`` is the entry as parsed from the manifest with
+    ``eventName`` and ``command`` removed — those two values already appear in
+    the identifier prefix, so hashing them would only reflect information the
+    consumer can already read.
+    """
+    return hashlib.sha256(canonical_json(declared_fields)).hexdigest()[:_DISCRIMINATOR_LENGTH]
+
+
+def derive_hook_id(
+    layer: str,
+    source_id: str,
+    event_name: str,
+    command: str,
+    siblings: Iterable[Mapping[str, Any]],
+    own_declared_fields: Mapping[str, Any],
+) -> str:
+    """Build the identifier string for a hook contribution.
+
+    The discriminator suffix is appended only when at least one sibling in the
+    same source shares the same ``(event_name, command)`` prefix. That keeps the
+    common case terse and the collision case unambiguous. ``siblings`` must
+    include every hook entry declared under this source (including the one
+    whose identifier is being derived); the function decides on its own whether
+    a collision exists.
+    """
+    base = f"{layer}:{source_id}:hook:{event_name}:{command}"
+    if _has_hook_sibling_collision(event_name, command, siblings):
+        return f"{base}:{hook_discriminator(own_declared_fields)}"
+    return base