From 87bec68e1f13088eb1f9cabf782a7577b82a926c Mon Sep 17 00:00:00 2001
From: wagesj45 <jordan@jordanwages.com>
Date: Tue, 19 Aug 2025 03:06:13 -0500
Subject: [PATCH] docs: add Design Philosophy and Args-Only Strings guidance
 for v2

---
 README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/README.md b/README.md
index e69de29..e014fad 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,54 @@
+Design Philosophy
+
+CS‑MIC is a small, embeddable expression interpreter designed primarily for UI scenarios where a user types flexible input (e.g., 2+2+someVar) but the host application needs a validated, deterministic numeric value. The library focuses on predictable evaluation, strong validation and extensibility through developer‑supplied variables and coded functions.
+
+Goals
+
+- Numeric‑first: Expressions evaluate to a numeric result the host can trust.
+- Predictable semantics: No implicit coercions or surprising operator behavior.
+- Embeddable: Tiny surface area, easy to host inside C# applications.
+- Extensible: Developers inject variables and ICodedFunction implementations.
+- Clear errors: Friendly, actionable diagnostics for invalid input.
+
+Core Principles
+
+- Determinism: The same input with the same variables/functions yields the same numeric output.
+- Minimalism: Keep the grammar and runtime small; add features only when they reinforce the numeric‑first mission.
+- Type clarity: Values carry explicit types; operators enforce type rules rather than auto‑converting.
+- Safe composition: Functions are pure from the interpreter’s perspective; side effects are the host’s responsibility.
+
+Strings: Arguments‑Only, Numeric‑First
+
+CS‑MIC’s v2 scope treats strings as helpers for functions, not as first‑class expression values. This preserves the “numeric guarantee” while enabling rich, domain‑specific function usage.
+
+- Where strings are allowed: As literals in function argument lists (e.g., myFunc("key", 42)).
+- Where strings are not allowed: As standalone primaries, in arithmetic (e.g., "a" + 1), or in comparisons; string variables are out of scope for v2.
+- Function contract: ICodedFunction implementations may accept string arguments and should return a numeric result when the function’s value is used in an expression.
+- Grammar posture: The grammar recognizes quoted string tokens; the parser accepts them only in function argument positions.
+- Operator semantics: No string operators or concatenation; no implicit conversions from string to number.
+- Errors: If a string is used outside an argument position or produced where a number is required, the interpreter emits a clear type error (e.g., "strings are only valid as function arguments").
+
+Rationale
+
+- Preserves the primary mission: turn flexible user input into a validated numeric value.
+- Keeps complexity low by avoiding general string semantics (concatenation, ordering, variables, etc.).
+- Maximizes developer power: functions can receive text payloads (formats, keys, expressions) and return numbers, leveraging CS‑MIC for parsing, validation and invocation.
+
+Developer Guidance
+
+- Implementing ICodedFunction: Inspect FunctionArgument.Value.Type to branch on expected input. If a string is required, validate and produce a numeric FunctionValue.
+- Argument metadata: Optionally use ExpectedArguments to document names and intended types for better diagnostics.
+- Error messaging: Prefer precise, actionable messages (e.g., "arg 'pattern' must be a string").
+
+Example
+
+// Pseudocode / sketch
+// myFunc("HEX", 0xFF) → 255
+// myFunc("BIN", 1010b) → 10
+// sumWithLabel("groupA", 1, 2, 3) → 6 (label used for logging/selection)
+
+Future Directions (Non‑Goals for v2)
+
+- First‑class strings: Allow strings as values, variables, or return types in general expressions (would require defining operators and comparisons).
+- Verbatim/opaque arguments: Special argument modes for embedding mini‑DSLs (higher parser complexity).
+- Value tagging: Optional metadata (e.g., OriginalLiteral) attached to FunctionValue for advanced scenarios.