Implement tryAs

Author: mitchpaulus

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `tryAs` checked cast: `<value> tryAs <type>` validates the value against the
+  type at runtime and pushes a `Maybe` — `just value` when it conforms, `none`
+  when it does not. Unlike `as` (a static-only checker hint), `tryAs` is meant
+  for data crossing a trust boundary such as `parseJson` output: one check at
+  the boundary and everything downstream is precisely typed. Compose with the
+  existing `?` unwrap for a die-loud form, e.g.
+  `"pkgs.json" parseJson tryAs Manifest ? :packages? (:name?) map`.
+  A `tryAs` whose source type could never be the target is a type error.
+
 - CLI completions for `cargo`: subcommands (including installed third-party
   ones via `cargo --list`), per-subcommand options, and dynamic values for
   `--target`, `--features`, `-p`/`--package`, `--bin`/`--example`/`--test`/`--bench`

ai/json_boundary_casts.md

@@ -0,0 +1,118 @@
+# Checked casts at the JSON boundary (`tryAs`)
+
+Status: implemented on branch `try-as` (2026-07-09). Doc pattern + `tryAs`
+both landed. One finding from implementation: `parseJson` maps every JSON
+number to `MShellFloat` (Go's default unmarshal), so `tryAs {str: int}` on
+JSON counts is always `none` — validate JSON numbers as `float`. Whether
+`parseJson` should produce `int` for integral numbers is an open follow-up.
+
+## Problem
+
+Drilling into parsed JSON under the type checker is painful.
+Extracting `.packages[].name` took four nested `match` blocks,
+because `parseJson` returns the wide union `list|dict|numeric|str|bool|null`
+and every union member must be handled at every level.
+Each `match dict:` arm proves a fact, uses it once, and throws the proof away —
+boilerplate scales with nesting depth.
+
+## What already works (and the doc gap)
+
+The static side of the fix already exists:
+
+```mshell
+type Manifest = {packages: [{name: str}]}
+
+"pkgs.json" parseJson as Manifest :packages? (:name?) map
+```
+
+This type-checks and runs today. `type_system.inc.html` even recommends the
+pattern ("prefer adding a named type and an `as` assertion near the boundary"),
+but `doc/mshell.md` — the doc agents actually read — never shows
+`parseJson ... as T`. **Cheapest immediate action: document this pattern in
+`doc/mshell.md`.**
+
+## The gap: `as` is static-only
+
+`as` is a checker hint with no runtime work (`Evaluator.go`, `MShellAsCast`
+case). When the JSON doesn't match the assertion, the failure surfaces late
+and badly: `{"packages": [{"name": 42}]}` through the cast above dies with
+`Cannot get length of a Float.` at a downstream call site, not at the boundary.
+
+## Design: `tryAs` — parse, don't validate
+
+One new checked cast that returns proof as a more precise type:
+
+```mshell
+"pkgs.json" parseJson tryAs Manifest      # ( -- Maybe[Manifest]), recoverable
+"pkgs.json" parseJson tryAs Manifest ?    # unwrap-or-die, composes with existing ?
+```
+
+- Runtime: structural walk of the value against the reified type expression.
+  JSON values are only dicts/lists/scalars, so the validator is a small
+  recursive function and structural checking is complete in this domain.
+- Success: `just` wrapping the value, statically typed `T`.
+  Downstream `:field?` / `map` need no further matching.
+- Failure: `none`.
+
+### Naming rationale
+
+- `as?` rejected: `?` consistently means *unwrap* a Maybe (`?`, `:field?`),
+  so a Maybe-*returning* `as?` reads backwards.
+- `as!` rejected: `!` means *store to variable* (`name!`).
+- `tryAs` follows the getter convention: base word returns Maybe,
+  existing `?` unwraps. Die-loud form is derived (`tryAs T ?`), not a
+  second primitive.
+
+### Division of labor with static `as`
+
+Both stay; the dividing line is trust boundaries:
+
+- `as` — value originates inside typed code: empty/ambiguous literals
+  (`[] as [str]`), narrowing inferred unions, branding. Checker can see
+  everything; runtime check would verify the statically obvious. Free.
+- `tryAs` — value crosses in from outside (parseJson, process output,
+  spreadsheets). Only the runtime can know the shape; pay one walk,
+  get a `Maybe[T]` proof.
+
+Possible follow-on: once `tryAs` exists, a hint diagnostic when bare `as`
+narrows an external-data union (e.g. the parseJson result) to a shape —
+"did you mean tryAs?" — while leaving literal-hint uses untouched.
+
+## Deferred (deliberately)
+
+- **Path-precise error messages.** `tryAs ... ?` failing as a bare `none`
+  loses ".packages[3].name: expected str, got float". A future Result type
+  with an error string is the planned home for this; the validator computes
+  the message internally anyway, so a Result-returning variant just exposes
+  it. The "no message on bad unwrap" problem is bigger than JSON and is not
+  being solved here.
+- **`dig` with typed default** (`json ['packages' 0 'name'] "unknown" dig`,
+  signature `(json [str|int] a -- a)`, default's type = result type via
+  existing generics). Nice for one-off drills without declaring a type.
+  If built: no `'*'` wildcard segments (they change the result shape and
+  break `a -- a`); `tryAs` + `map` owns extract-many. Conflates missing
+  with the sentinel value.
+- **Recursive types** (`type Json = int | str | [Json]`) don't work today —
+  the name isn't in scope inside its own body. A first-class "any JSON"
+  type would need checker work; with checked casts at the boundary it's
+  rarely needed.
+
+## Implementation notes
+
+Structure (after review feedback on exhaustiveness): there is no separate
+validator file. `TypeExpr.go` defines a `TypeExpression` interface
+(`MShellParseItem` + `validateObj`) that every type-expression node must
+implement, and the parser productions return it — so a new node kind
+without runtime validation does not compile. Built-in named types (bytes,
+null, path, datetime, Grid, GridView, GridRow) live in one
+`builtinNamedTypes` table consulted by BOTH the checker's resolveTypeExpr
+and the runtime validator, so a type cannot be half-added; a name missing
+from the table does not exist statically either. `Maybe` (parametric) and
+`none` (constructor, not a type) are deliberately special-cased outside
+the table.
+
+- Type declarations are currently erased at runtime (`MShellTypeDecl` is
+  static-only). `tryAs` needs type expressions reified into the evaluator
+  so the validator can walk them.
+- The shape language already covers everything JSON needs: shapes, optional
+  fields (`name?: T`), unions, `null` vs `none`, `Maybe`.

doc/mshell.md

@@ -564,6 +564,33 @@ type Row = [Cell]
 { "name": "Ada", "age": 36 } as Person :age? 1 +
 ```
 
+`as` is a static-only assertion: a hint to the checker with no runtime work.
+Use it when the value originates inside typed code and the checker just needs help — typing an empty literal (`[] as [str]`), narrowing an inferred union, or tagging a literal into a named type.
+
+`tryAs` is the checked cast for data crossing a trust boundary (parseJson output, process output, spreadsheet rows).
+It validates the value against the type at runtime and pushes a `Maybe`: `just value` when it conforms, `none` when it does not.
+This is the "parse, don't validate" pattern: one check at the boundary, and everything downstream is precisely typed with no match boilerplate.
+Compose with the existing `?` unwrap for the die-loud form.
+
+```mshell
+type Manifest = {packages: [{name: str}]}
+
+# Recoverable: handle bad input with one match at the boundary.
+"pkgs.json" parseJson tryAs Manifest match
+    just m : @m :packages? (:name?) map,
+    none   : [],
+end
+
+# Die-loud: unwrap immediately when malformed input should stop the script.
+"pkgs.json" parseJson tryAs Manifest ? :packages? (:name?) map
+```
+
+A `tryAs` whose source type can never be the target (e.g. `5 tryAs str`) is flagged by the checker, since it would always produce `none`.
+Shape validation allows extra keys, requires all non-optional fields, and validates optional fields only when present.
+A `none` conforms to `Maybe[T]` for every `T`; quotation types are checked by kind only (signatures are not verified at runtime).
+Named types must be declared before the cast runs.
+Note that `parseJson` produces a `float` for every JSON number, so validate JSON numbers as `float`, not `int`.
+
 Dictionary types are split into homogeneous dictionaries and shapes.
 A homogeneous dictionary is for dynamic keys where every value has the same type.
 In a type expression, write `{str: int}`.
@@ -1060,7 +1087,7 @@ end wl # Output: 11
 - `gridValues`: Extract Grid or GridView cell values as row-major lists, without a header row and without coercing cell types. (`Grid|GridView -- [[a]]`)
 - `toCsvCell`: Escape a single CSV cell. If the value contains `,`, `"`, or a newline, wraps the value in double quotes and doubles any embedded quotes; otherwise returns the input unchanged. (`str -- str`)
 - `toCsv`: Serialize a list of rows to a CSV string. Each cell is escaped with `toCsvCell`, cells are joined with `,`, and rows are joined with `\n`. (`[[str]] -- str`)
-- `parseJson`: Parse JSON from a string, binary, or file path into mshell objects. JSON `null` becomes the `null` type (distinct from `none`). (`path|str|binary -- list|dict|numeric|str|bool|null`)
+- `parseJson`: Parse JSON from a string, binary, or file path into mshell objects. JSON `null` becomes the `null` type (distinct from `none`); every JSON number becomes a `float`. Narrow the result with `tryAs` (checked, boundary data) or `as` (static hint). (`path|str|binary -- list|dict|numeric|str|bool|null`)
 - `parseExcel`: Parse an `.xlsx` (OOXML) spreadsheet into a list of sheets in workbook (tab) order. Each sheet is a dict with a `name` key (the worksheet name), a `data` key holding a rectangular list of rows (list of lists), a `hidden` key (bool; `true` for hidden or veryHidden sheets), and a `visibility` key (`"visible"`, `"hidden"`, or `"veryHidden"`). Cell values are typed: numbers become floats (dates appear as Excel serial floats), strings become strings (shared, inline, and formula-string results all resolved), booleans become booleans, error cells (e.g. `#DIV/0!`) become `none`, and empty/padding cells are the empty string. Chartsheets are skipped; hidden worksheets are included. Dates are returned as raw Excel serial floats; apply `fromOleDate` at the call site to convert. `parseExcel` assumes the default 1900-based date system, which matches `fromOleDate`'s OLE epoch (1899-12-30). Workbooks saved with the 1904 date system (`<workbookPr date1904="true"/>`, seen on some files originally authored on older Mac Excel or with the "Use 1904 date system" option enabled) have serials offset by 1462 days; on those files, add 1462 to each serial before calling `fromOleDate`, e.g. `@wb :0: :data? :3: :0: 1462 + fromOleDate`. (`path|binary -- list`)
 - `seq`: Generate a list of integers, starting from 0. Exclusive end to integer on stack. `2 seq` produces `[0 1]`. `(int -- [int])`
 - `repeat`: Create a list containing the provided value repeated `n` times. `(a int -- [a])`

doc/type_system.inc.html

@@ -153,6 +153,44 @@ <h1 id="type-system-type-expressions">Type Expressions <a class="section-link" h
 
 <pre><code>{ "name": "Ada", "age": 36 } as Person</code></pre>
 
+<h2 id="type-system-tryas">Checked casts with <code>tryAs</code> <a class="section-link" href="#type-system-tryas" aria-label="Permalink">§</a></h2>
+
+<p>
+<code>as</code> is a static-only assertion: a hint to the checker with no runtime work.
+That is the right tool when the value originates inside typed code — typing an empty literal (<code>[] as [str]</code>), narrowing an inferred union, or tagging a literal into a named type — because the checker can already see everything it needs.
+</p>
+
+<p>
+<code>tryAs</code> is the checked cast for data crossing a trust boundary, such as <code>parseJson</code> output, process output, or spreadsheet rows.
+It validates the value against the type expression at runtime and pushes a <code>Maybe</code>: <code>just value</code> when the value conforms, <code>none</code> when it does not.
+This is the "parse, don't validate" pattern: one check at the boundary hands the checker a precise type, so everything downstream needs no further matching.
+The existing <code>?</code> unwrap composes for the die-loud form.
+</p>
+
+<pre><code>type Manifest = {packages: [{name: str}]}
+
+# Recoverable: handle bad input with one match at the boundary.
+"pkgs.json" parseJson tryAs Manifest match
+    just m : @m :packages? (:name?) map,
+    none   : [],
+end
+
+# Die-loud: unwrap immediately when malformed input should stop the script.
+"pkgs.json" parseJson tryAs Manifest ? :packages? (:name?) map</code></pre>
+
+<p>
+A <code>tryAs</code> whose source type can never be the target (for example <code>5 tryAs str</code>) is a type error, since the runtime check would always produce <code>none</code>.
+</p>
+
+<p>
+Validation semantics mirror the <code>match</code> block's type arms.
+<code>int</code> matches an integer only — note that <code>parseJson</code> produces a <code>float</code> for every JSON number, so validate JSON numbers as <code>float</code>.
+Shape validation allows extra keys (width subtyping), requires all non-optional fields, and validates optional fields only when present.
+A <code>none</code> conforms to <code>Maybe[T]</code> for every <code>T</code>; a <code>just</code> validates its inner value.
+Quotation types are checked by kind only — signatures are not verified at runtime.
+A named type must have been declared before the cast runs.
+</p>
+
 <h1 id="type-system-dictionaries">Dictionaries <a class="section-link" href="#type-system-dictionaries" aria-label="Permalink">§</a> <a class="back-to-top" href="#type-system-top">Back to top</a></h1>
 
 <p>

mshell/Evaluator.go

@@ -396,6 +396,11 @@ type EvalState struct {
 
 	defIndex    map[string]int
 	defIndexLen int
+
+	// typeDefs is the runtime type environment: `type Name = <typeExpr>`
+	// declarations register their body AST here so `tryAs Name` can
+	// resolve named types during validation.
+	typeDefs map[string]TypeExpression
 }
 
 // RebuildDefinitionIndex records the first index for each name, matching
@@ -906,18 +911,54 @@ func (state *EvalState) processToken(token MShellParseItem, frame *EvaluationFra
 		return state.processTokenToken(t, frame, frames)
 
 	case *MShellTypeDecl:
-		// Static-only: type declarations have no runtime effect by design.
+		// Registers the declaration for `tryAs`; otherwise static-only.
+		state.registerTypeDecl(t)
 		return SimpleSuccess()
 
 	case *MShellAsCast:
 		// Static-only: `as` is a checker hint; no runtime work.
 		return SimpleSuccess()
 
+	case *MShellTryAsCast:
+		return state.processTryAsCast(t, stack)
+
 	default:
 		return state.FailWithMessage(fmt.Sprintf("Unknown token type: %T\n", token))
 	}
 }
 
+// registerTypeDecl records a `type Name = <typeExpr>` declaration in the
+// runtime type environment for `tryAs`. The checker flags duplicate
+// declarations; at runtime the latest evaluation wins.
+func (state *EvalState) registerTypeDecl(decl *MShellTypeDecl) {
+	if state.typeDefs == nil {
+		state.typeDefs = make(map[string]TypeExpression, 8)
+	}
+	state.typeDefs[decl.Name] = decl.Body
+}
+
+// processTryAsCast implements the runtime of `tryAs`: pop a value,
+// validate it structurally against the type expression, and push
+// `just value` when it conforms or `none` when it does not. The
+// validation error return is reserved for malformed casts (an unknown
+// type name), which fail the script rather than producing a `none`.
+func (state *EvalState) processTryAsCast(cast *MShellTryAsCast, stack *MShellStack) EvalResult {
+	obj, err := stack.Pop()
+	if err != nil {
+		return state.FailWithMessage(fmt.Sprintf("%d:%d: 'tryAs' requires a value on the stack.\n", cast.TryAsToken.Line, cast.TryAsToken.Column))
+	}
+	conforms, verr := cast.Target.validateObj(state, obj)
+	if verr != nil {
+		return state.FailWithMessage(fmt.Sprintf("%d:%d: %s\n", cast.TryAsToken.Line, cast.TryAsToken.Column, verr.Error()))
+	}
+	if conforms {
+		stack.Push(&Maybe{obj: obj})
+	} else {
+		stack.Push(&Maybe{obj: nil})
+	}
+	return SimpleSuccess()
+}
+
 // callDefinition handles calling a definition with TCO support
 func (state *EvalState) callDefinition(def MShellDefinition, token Token, frame *EvaluationFrame, frames *[]EvaluationFrame) EvalResult {
 	newContext := frame.Context.CloneLessVariables()
@@ -3222,8 +3263,14 @@ func (state *EvalState) evaluateItems(objects []MShellParseItem, stack *MShellSt
 			}
 		case *MShellAsCast:
 			// Static-only: `as` is a checker hint; no runtime work.
+		case *MShellTryAsCast:
+			result := state.processTryAsCast(t, stack)
+			if result.ShouldPassResultUpStack() {
+				return result
+			}
 		case *MShellTypeDecl:
-			// Static-only: type declarations have no runtime effect by design.
+			// Registers the declaration for `tryAs`; otherwise static-only.
+			state.registerTypeDecl(t)
 		default:
 			return state.FailWithMessage(fmt.Sprintf("We haven't implemented the type '%T' yet.\n", t))
 		}

mshell/Lexer.go

@@ -109,6 +109,7 @@ const (
 	TRY
 	FAIL_KEYWORD
 	PURE
+	TRYAS
 )
 
 func (t TokenType) String() string {
@@ -283,6 +284,8 @@ func (t TokenType) String() string {
 		return "AS"
 	case TYPE:
 		return "TYPE"
+	case TRYAS:
+		return "TRYAS"
 	case TRY:
 		return "TRY"
 	case FAIL_KEYWORD:
@@ -621,6 +624,9 @@ func (l *Lexer) literalOrKeywordType() TokenType {
 					case 'u':
 						return l.checkKeyword(3, "e", TRUE)
 					case 'y':
+						if l.curLen() > 3 {
+							return l.checkKeyword(3, "As", TRYAS)
+						}
 						return l.checkKeyword(3, "", TRY)
 					}
 				}

mshell/Lexer_test.go

@@ -13,6 +13,7 @@ func TestTypeCheckerKeywords(t *testing.T) {
 		{"as", AS},
 		{"type", TYPE},
 		{"try", TRY},
+		{"tryAs", TRYAS},
 		{"fail", FAIL_KEYWORD},
 		{"pure", PURE},
 		// Make sure neighbors still tokenize as before.
@@ -23,6 +24,8 @@ func TestTypeCheckerKeywords(t *testing.T) {
 		{"types", LITERAL},
 		{"asx", LITERAL},
 		{"trying", LITERAL},
+		{"tryAsX", LITERAL},
+		{"tryas", LITERAL},
 		{"failed", LITERAL},
 		{"purest", LITERAL},
 	}

mshell/Parser.go

@@ -1102,6 +1102,8 @@ func (parser *MShellParser) ParseItem() (MShellParseItem, error) {
 		return parser.ParsePrefixQuote()
 	case AS:
 		return parser.ParseAsCast()
+	case TRYAS:
+		return parser.ParseTryAsCast()
 	default:
 		return parser.ParseSimple(), nil
 	}

mshell/TypeCast.go

@@ -151,6 +151,37 @@ func (c *Checker) Cast(target TypeId, callSite Token) {
 	c.stack.Push(target)
 }
 
+// TryCast implements `<value> tryAs <target>`. It pops the top of the
+// stack and pushes Maybe[target]. The same compatibility rule as Cast
+// applies, but for the opposite reason: a source that could never be the
+// target makes the runtime check always-none, which is almost certainly
+// a bug, so it is reported. The runtime narrowing itself (wide union in,
+// precise type out wrapped in Maybe) is exactly the case Cast's generous
+// direction already blesses.
+func (c *Checker) TryCast(target TypeId, callSite Token) {
+	if c.stack.Len() == 0 {
+		c.errors = append(c.errors, TypeError{
+			Kind: TErrStackUnderflow,
+			Pos:  callSite,
+			Hint: "tryAs",
+		})
+		c.stack.Push(c.arena.MakeMaybe(target))
+		return
+	}
+	top := c.stack.items[len(c.stack.items)-1]
+	c.stack.items = c.stack.items[:len(c.stack.items)-1]
+
+	if !c.castOk(top, target) {
+		c.errors = append(c.errors, TypeError{
+			Kind:     TErrInvalidCast,
+			Pos:      callSite,
+			Expected: target,
+			Actual:   top,
+		})
+	}
+	c.stack.Push(c.arena.MakeMaybe(target))
+}
+
 // castOk reports whether `src` can be cast to `dst`.
 //
 // Trials, in order (each isolated by a substitution checkpoint):