refinements from architecture meeting

Author: audreyality

docs/contributing/code-style/enums.md

@@ -7,15 +7,9 @@ use [constant objects][constant-object-pattern] instead of introducing a new enu
 
 - Use the same name for your type- and value-declaration.
 - Use `type` to derive type information from the const object.
+- Avoid asserting the type of an enum-like. Use explicit types instead.
 - Create utilities to convert and identify enums modelled as primitives.
 
-:::tip
-
-This pattern should simplify the usage of your new objects, improve type safety in files that have
-adopted TS-strict, and make transitioning an enum to a const object much easier.
-
-:::
-
 ### Example
 
 Given the following enum:
@@ -33,14 +27,16 @@ export enum CipherType = {
 You can redefine it as an object like so:
 
 ```ts
-const CipherType = {
+// freeze to prevent member injection
+export const CipherType = Object.freeze({
   Login: 1,
   SecureNote: 2,
   Card: 3,
   Identity: 4,
   SshKey: 5,
-} as const;
+} as const);
 
+// derive the enum-like type from the raw data
 export type CipherType = CipherType[keyof typeof CipherType];
 ```
 
@@ -55,6 +51,11 @@ function doSomething(type: CipherType) {}
 
 // And used as a value (just like a regular `enum`)
 doSomething(CipherType.Card);
+
+// advanced use-case: discriminated union definition
+type CipherContent =
+  | { type: typeof CipherType.Login, username: EncString, ... }
+  | { type: typeof CipherType.SecureNote, note: EncString, ... }
 ```
 
 :::warning
@@ -64,17 +65,24 @@ like the following requires you explicitly type your variables:
 
 ```ts
 // ✅ Do: strongly type enum-likes
-const subject = new Subject<CipherType>();
 let value: CipherType = CipherType.Login;
+const array: CipherType[] = [CipherType.Login];
+const subject = new Subject<CipherType>();
 
 // ❌ Do not: use type inference
-const array = [CipherType.Login]; // infers `number[]`
 let value = CipherType.Login; // infers `1`
+const array = [CipherType.Login]; // infers `number[]`
+
+// ❌ Do not: use type assertions
+let value = CipherType.Login as CipherType; // this operation is unsafe
 ```
 
 :::
 
-The following utilities may assist introspection:
+## Utilities
+
+The following utilities can be used to maintain type safety after compilation. This code assumes
+`const CipherType` is frozen.
 
 ```ts
 import { CipherType } from "./cipher-type";