# Outstanding Questions for Manager Review

## Branch Context

**Current branch:** `refactor/unify-typeregistry` **Based on:**
`feature/wish-schemas` branch

The `refactor/unify-typeregistry` branch builds on top of the `wish-schemas`
work, which added schema generation support for the `wish` built-in function.

## Phase 4: Outstanding Design Questions

### 1. Underscore Prefix Edge Cases

**Context:** We implemented the never/unknown refinement with this rule:

- Parameters with `_` prefix and no type → `false` schema (never)

**Manager's concern:**

> "_ is just a convention for the linter to not complain about unused variables,
> it doesn't necessarily mean it isn't used..."

**Question:** Should we validate that `_` prefixed parameters are actually
unused before assigning them `false` schema? Or is the current heuristic
acceptable?

**Current behavior:**

```typescript
// This gets false schema even if _event is used in the body
handler((_event, state) => {
  console.log(_event); // Using it despite underscore
  state.value.set(state.value.get() + 1);
});
```

**Options:**

- **A) Keep current heuristic**: Simple, relies on developer convention
- **B) Add usage analysis**: Check if parameter is actually referenced in
  function body before using `false` schema
- **C) Require explicit ignore pattern**: Use a different convention like
  `__event` or comment annotation

**Impact:** Low - most code follows the convention correctly, but edge cases
could cause confusion

---

### 2. Generic Helper Functions with `derive` (from wish-schemas branch)

**Context:** When users write generic helper functions that use `derive`, our
transformer can't generate schemas because type parameters are uninstantiated at
the function definition site.

**Example from `note.tsx`:**

```typescript
function schemaifyWish<T>(path: string, def: T) {
  return derive(wish<T>(path), (i) => i ?? def);
  // Can't generate schema - T is not concrete until call site
}

const mentionable = schemaifyWish<MentionableCharm[]>("#mentionable", []);
```

**Current behavior:** Graceful degradation - function compiles but loses
compile-time schemas

**Question:** Is graceful degradation acceptable, or should we invest in
call-site transformation?

**Options:**

**Option 1: Accept Current Behavior (Graceful Degradation)**

- ✅ No crashes, patterns compile successfully
- ✅ Works for non-generic code (99% of cases)
- ✅ Simple architecture
- ❌ Generic helper functions lose compile-time schemas
- ❌ Runtime must handle untyped form

**Option 2: Implement Call-Site Transformation**

- ✅ Full schema support for generic functions
- ❌ Significantly more complex transformer architecture
- ❌ Potential performance impact
- ❌ May require architectural changes to transformer pipeline

**Possible approaches for Option 2:**

- Function inlining: Expand function body at call sites (changes semantics)
- Deferred transformation: Mark generic functions, transform calls in later pass
- Runtime schema generation: Generate schemas at runtime using reflection

**Impact assessment:**

- Current usage of generic helpers with `derive` in codebase: Unknown (needs
  audit)
- Risk: Users may not realize schemas aren't being generated
- Workaround: Users can avoid generic helpers, or add explicit type annotations

**Documentation:** See `packages/ts-transformers/type-parameter-schema-issue.md`
for full analysis

---

### 3. Type Inference Enhancement Opportunities

**Context:** During implementation, we identified cases where type inference
could be improved but isn't currently.

**Example:**

```typescript
// TypeScript could theoretically infer number here
<span>Count: {derive(items.length, (n) => n + 1)}</span>;
//                  ^^^^^^^^^^^^ is number, so n should be number
```

**Current behavior:** Falls back to `true` (unknown) schema because parent
function parameters lack type annotations

**Question:** Should we invest in enhanced type inference from:

- Property access on known types (`items.length` → number)
- Arithmetic operations (`n + 1` → number)
- Other JavaScript semantics

**Tradeoffs:**

- ✅ Better schema generation without explicit types
- ✅ Improved developer experience
- ❌ Adds complexity to type inference logic
- ❌ May not cover all cases anyway

**Impact:** Medium - would improve DX but not critical for functionality

---

## Recommendations

### Priority 1: Generic Functions Question (Critical for Architecture)

**Needs decision:** Should we plan for call-site transformation or accept
current limitations?

- Affects long-term architecture decisions
- Related to the `wish-schemas` work that motivated this branch

### Priority 2: Underscore Prefix Validation (Low Risk)

**Recommendation:** Keep current heuristic unless we see real-world issues

- Simple and aligns with TypeScript/linter conventions
- Can add validation later if needed

### Priority 3: Type Inference Enhancement (Future Work)

**Recommendation:** Defer - nice-to-have but not blocking

- Current fallback to `unknown` is reasonable
- Users can add type annotations when needed

---

## Current Status

✅ **Phase 3 Complete:** Never/unknown refinement fully implemented and tested

- All transformers (handler, pattern, recipe, derive, lift) use refined fallback
- 30+ test fixtures updated
- All tests passing (16 suites, 180 steps)

📋 **Ready for:** Manager review on outstanding design questions above