docs(ShaderCache): add @remarks to getProgramKey JSDoc documenting key-stability invariant

[Copilot]

getProgramKey's JSDoc lacked any warning that for collision-resolved programs (stored under the composite hashKey:secondaryKey slot), the key returned can differ from what a subsequent call would return once the primary-hash slot is vacated — a subtle footgun in advanced retain/release flows.

Changes

src/core/ShaderCache.ts

• Added @remarks block to getProgramKey JSDoc, placed after the existing code example
• Documents the call-order requirement (getProgramKey before or immediately after getProgram) and the eviction-driven key instability in the collision-resolved case
• Existing getProgram → getProgramKey → retainProgram → releaseProgram example preserved verbatim

* @remarks
* Always call `getProgramKey` **before** `getProgram` (or immediately after,
* while the program is still cached) to guarantee the returned key matches the
* slot actually used. In the rare case of a hash collision, the resolved
* composite key (`primary:secondary`) is stable for the lifetime of the cached
* entry, but may differ from what a later call would return if the entry has
* been evicted.

tests/shader.test.ts

• Added shaderCacheSource read via readFileSync (mirrors the existing materialSource pattern)
• New describe('ShaderCache JSDoc') block with four source-text assertions:
  • @remarks block exists in getProgramKey's JSDoc
  • Remarks body contains both before and getProgram
  • Remarks body contains evicted
  • Original code example (getProgramKey / retainProgram / releaseProgram) is intact

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[PATCH] ShaderCache — getProgramKey JSDoc example omits warning about auto-keyed collision-resolved programs</issue_title>
<issue_description>Category: documentation
Severity: patch
File(s): src/core/ShaderCache.ts

Description

The JSDoc for getProgramKey includes a usage example showing the typical getProgram → getProgramKey → retainProgram → releaseProgram flow. However, it does not warn callers that for auto-keyed programs whose slot resolved to the composite collision key (hashKey:secondaryKey), calling getProgramKey a second time after the primary-hash slot has been vacated may theoretically return a different key than was used at getProgram time. This subtle invariant is worth documenting to avoid misuse in advanced caching scenarios.

Problematic code example

/**
 * Return the cache key that `getProgram` uses (or would use) for the given
 * source pair...
 *
 * ```ts
 * const key = cache.getProgramKey(vertSrc, fragSrc);
 * const program = cache.getProgram(vertSrc, fragSrc);
 * cache.retainProgram(key);
 * // … later …
 * cache.releaseProgram(key);
 * ```
 */

Suggested fix

Add a @remarks note explaining the key-stability invariant:

/**
 * ...existing description...
 *
 * @remarks
 * Always call `getProgramKey` **before** `getProgram` (or immediately after,
 * while the program is still cached) to guarantee the returned key matches the
 * slot actually used. In the rare case of a hash collision, the resolved
 * composite key (`primary:secondary`) is stable for the lifetime of the cached
 * entry, but may differ from what a later call would return if the entry has
 * been evicted.
 */

Acceptance criteria

• A @remarks block documents key-stability expectations
• The existing code example is preserved unchanged
• No functional code is changed</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [PATCH] ShaderCache — getProgramKey JSDoc example omits warning about auto-keyed collision-resolved programs #361

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.