From 7202e65a075400fbd5620c84a1c95ef819d8d2ad Mon Sep 17 00:00:00 2001
From: Philipinho <16838612+Philipinho@users.noreply.github.com>
Date: Thu, 23 Apr 2026 23:34:05 +0100
Subject: [PATCH] feat(base-formula): add parse-error and cell-error sentinels

---
 packages/base-formula/src/error.ts        | 40 +++++++++++++++++++++++
 packages/base-formula/src/index.client.ts |  1 +
 packages/base-formula/src/index.server.ts |  1 +
 3 files changed, 42 insertions(+)
 create mode 100644 packages/base-formula/src/error.ts

diff --git a/packages/base-formula/src/error.ts b/packages/base-formula/src/error.ts
new file mode 100644
index 000000000..c5cc0e0d3
--- /dev/null
+++ b/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"
+  );
+}
diff --git a/packages/base-formula/src/index.client.ts b/packages/base-formula/src/index.client.ts
index bebab0e16..da1dd3eab 100644
--- a/packages/base-formula/src/index.client.ts
+++ b/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";
diff --git a/packages/base-formula/src/index.server.ts b/packages/base-formula/src/index.server.ts
index 77ea21d3f..0d93857dd 100644
--- a/packages/base-formula/src/index.server.ts
+++ b/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";