Derive SparkType union from const assertion

[UniquePixels]

Context

Audit ID: ARCH-3

The `SPARK_TYPES` set in `loader.ts` contains literal strings that must match the `SparkType` union. If a new spark type is added to the union but not the set, `isSpark()` will silently reject valid sparks.

Approach

Derive `SparkType` from a `const` assertion array, and build the Set from the same source of truth. This ensures the union and runtime set can never diverge.

Files

• `src/core/sparks/loader.ts` (L55-60)
• Type definition file for `SparkType`

[coderabbitai]

Coding Plan

Summary

• Define spark type identifiers once as a const assertion array in src/core/guards/index.ts
• Derive the SparkType union type from that array using indexed access
• Import the array in loader.ts to construct the runtime Set, eliminating duplication
• No changes to public API or external consumers—only the internal implementation is consolidated

Implementation Steps

Unify SparkType Definition and Runtime Set

This phase consolidates the two separate definitions into a single source of truth using TypeScript's const assertion pattern.

Task 1: Task 1.1: Convert SparkType to Const-Derived Type

Refactor the SparkType definition in src/core/guards/index.ts to derive from a const assertion array rather than being manually defined as a union.

• Create a new exported const array SPARK_TYPES with as const assertion containing the four spark type literals
• Replace the existing SparkType union definition with an indexed access type derived from the const array: type SparkType = (typeof SPARK_TYPES)[number]
• Ensure the array is exported so it can be imported by other modules

Task 2: Task 1.2: Update Loader to Use Shared Source of Truth

Modify src/core/sparks/loader.ts to build its runtime Set from the shared const array instead of maintaining duplicate literals.

• Import SPARK_TYPES const array from @/core/guards alongside the existing SparkType type import
• Replace the locally-defined SPARK_TYPES Set initialization to construct from the imported array: new Set(SPARK_TYPES)
• Remove the duplicated string literals from loader.ts
• The isSpark() function requires no changes as it already references the module-scoped SPARK_TYPES Set

🤖 Prompt for AI agents

This phase consolidates the `SparkType` union type and `SPARK_TYPES` runtime Set
into a single source of truth using TypeScript's const assertion pattern.

**File: `src/core/guards/index.ts`**
- Create a new exported const array named `SPARK_TYPES` using an `as const`
assertion, containing the four spark type string literals: `'command'`,
`'component'`, `'gateway-event'`, and `'scheduled-event'`
- Remove the existing manually written `SparkType` union type definition
- Replace it with an indexed access type derived from the array: `type SparkType
= (typeof SPARK_TYPES)[number]`
- Ensure `SPARK_TYPES` is exported so it can be imported by other modules

**File: `src/core/sparks/loader.ts`**
- Import the `SPARK_TYPES` const array from `@/core/guards` (alongside any
existing `SparkType` type import)
- Remove the locally-defined `SPARK_TYPES` Set and its hardcoded string literals
- Replace the Set initialization with `new Set(SPARK_TYPES)` using the imported
array
- Leave the `isSpark()` function unchanged, as it already references the
module-scoped `SPARK_TYPES` Set

Research

The codebase defines SparkType as a string literal union in src/core/guards/index.ts, which is re-exported from src/core/sparks/index.ts. A separate SPARK_TYPES Set with identical values exists privately in src/core/sparks/loader.ts and is used by the isSpark() type guard to validate spark instances at runtime. Both locations currently hardcode the same four values: 'command', 'component', 'gateway-event', and 'scheduled-event'.

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase consolidates the `SparkType` union type and `SPARK_TYPES` runtime Set
into a single source of truth using TypeScript's const assertion pattern.

**File: `src/core/guards/index.ts`**
- Create a new exported const array named `SPARK_TYPES` using an `as const`
assertion, containing the four spark type string literals: `'command'`,
`'component'`, `'gateway-event'`, and `'scheduled-event'`
- Remove the existing manually written `SparkType` union type definition
- Replace it with an indexed access type derived from the array: `type SparkType
= (typeof SPARK_TYPES)[number]`
- Ensure `SPARK_TYPES` is exported so it can be imported by other modules

**File: `src/core/sparks/loader.ts`**
- Import the `SPARK_TYPES` const array from `@/core/guards` (alongside any
existing `SparkType` type import)
- Remove the locally-defined `SPARK_TYPES` Set and its hardcoded string literals
- Replace the Set initialization with `new Set(SPARK_TYPES)` using the imported
array
- Leave the `isSpark()` function unchanged, as it already references the
module-scoped `SPARK_TYPES` Set

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#6 - 🌈 improve(testing): consolidate test utilities [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!