feat(base-formula): add parse-error and cell-error sentinels

packages/base-formula/src/error.ts

@@ -0,0 +1,40 @@
+// packages/base-formula/src/error.ts
+import type { ErrorCell, ErrorCode } from "./types";
+
+export type ParseErrorCode =
+  | "UNEXPECTED_TOKEN"
+  | "UNEXPECTED_EOF"
+  | "UNKNOWN_PROPERTY"
+  | "UNKNOWN_FUNCTION"
+  | "ARITY_MISMATCH"
+  | "TYPE_MISMATCH"
+  | "CYCLE";
+
+export type ParseError = {
+  code: ParseErrorCode;
+  message: string;
+  span: { start: number; end: number };
+  hint?: string;
+};
+
+export class FormulaParseError extends Error {
+  readonly errors: ParseError[];
+  constructor(errors: ParseError[]) {
+    super(errors.map((e) => `${e.code}: ${e.message}`).join("; "));
+    this.errors = errors;
+    this.name = "FormulaParseError";
+  }
+}
+
+export function makeErrorCell(code: ErrorCode, msg: string): ErrorCell {
+  return { __err: code, msg, v: 1 };
+}
+
+export function isErrorCell(v: unknown): v is ErrorCell {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "__err" in v &&
+    typeof (v as { __err: unknown }).__err === "string"
+  );
+}

packages/base-formula/src/index.client.ts

@@ -2,3 +2,4 @@
 // Does NOT export eval or the function registry.
 export * from "./ast";
 export * from "./types";
+export * from "./error";

packages/base-formula/src/index.server.ts

@@ -1,3 +1,4 @@
 // Server-side public surface: everything in client + evaluator + registry.
 export * from "./ast";
 export * from "./types";
+export * from "./error";