@forthix/forthic 0.4.0 → 0.5.1

package/README.md

@@ -4,7 +4,7 @@
 
 Use Forthic to wrap your TypeScript/JavaScript code within composable words, leveraging categorical principles for clean, powerful abstractions.
 
-**[Forthic Parent Documentation](https://github.com/forthix/forthic)** | **[Getting Started with forthic-ts](#getting-started)** | **[Examples](examples/)** | **[API Docs](docs/)**
+**[Learn at forthix.com](https://forthix.com)** | **[Forthic Docs](https://github.com/forthix/forthic)** | **[Getting Started](#getting-started)** | **[Examples](examples/)** | **[API Docs](docs/)**
 
 ---
 
@@ -16,7 +16,9 @@ Forthic enables **categorical coding** - a way to solve problems by viewing them
 2. **Compose transformations** cleanly using stack-based operations
 3. **Build powerful abstractions** from simple primitives
 
-See the [Forthic repository](https://github.com/forthix/forthic) for philosophy, core concepts, and why categorical coding matters.
+**[Learn more about Categorical Coding →](https://forthix.com/blog/category-theory-for-the-rest-of-us-coders)**
+
+See the [Forthic repository](https://github.com/forthix/forthic) for technical documentation and API references.
 
 ---
 
@@ -200,6 +202,10 @@ import { GrpcClient, RemoteModule, startGrpcServer } from '@forthix/forthic/grpc
 
 ## Documentation
 
+### Learning Resources
+- **[forthix.com](https://forthix.com)** - Learn about Forthic and Categorical Coding
+- **[Category Theory for Coders](https://forthix.com/blog/category-theory-for-the-rest-of-us-coders)** - Understand the foundations
+
 ### This Runtime
 - **[Getting Started](docs/getting-started.md)** - TypeScript-specific setup
 - **[Module API Reference](docs/modules/)** - Standard library documentation

package/dist/cjs/forthic/decorators/schemaUtils.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/**
+ * Registry metadata types for stack objects and class instances.
+ */
+type StackObjectMetadata = {
+    objectType: "stackObject";
+    stackObjectType: string;
+    className?: undefined;
+    OriginalClass?: undefined;
+} | {
+    objectType: "class";
+    OriginalClass: new (...args: any[]) => any;
+    className: string;
+    stackObjectType?: undefined;
+};
+/**
+ * Track metadata for schema comparison in tests and documentation.
+ * Only required for schemas that can't be compared out of the box,
+ * like custom schemas or instanceof schemas.
+ */
+export declare const stackObjectRegistry: z.core.$ZodRegistry<StackObjectMetadata, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+/**
+ * Creates a Zod schema for stack objects that have a stackObjectType property.
+ * This is a helper to reduce boilerplate when creating custom stack object schemas.
+ * It also ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.custom() directly for stack objects.
+ *
+ * @example
+ * ```ts
+ * interface StackEmail {
+ *   stackObjectType: "email";
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * }
+ *
+ * const stackEmailSchema = createStackObjectSchema<StackEmail>("email");
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(email:${stackEmailSchema} -- sent:${z.boolean()})`, "Send email")
+ * async SEND(email: StackEmail): Promise<boolean> { ... }
+ * ```
+ */
+export declare function createStackObjectSchema<T extends {
+    stackObjectType: string;
+}>(stackObjectType: string, errorMessage?: string): z.ZodCustom<T>;
+/**
+ * Creates a Zod instanceof schema with automatic metadata registration.
+ * This ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.instanceof() directly.
+ *
+ * @example
+ * ```ts
+ * import { Temporal } from "temporal-polyfill";
+ *
+ * const plainDateSchema = createInstanceOfSchema(Temporal.PlainDate);
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(date:${plainDateSchema} -- formatted:${z.string()})`, "Format date")
+ * async FORMAT(date: Temporal.PlainDate): Promise<string> { ... }
+ * ```
+ */
+export declare function createInstanceOfSchema<T extends abstract new (...args: any[]) => any>(ClassToSchematize: T, 
+/** If not passed, falls back to class.name */
+className?: string): z.ZodType<InstanceType<T>>;
+export {};

package/dist/cjs/forthic/decorators/schemaUtils.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stackObjectRegistry = void 0;
+exports.createStackObjectSchema = createStackObjectSchema;
+exports.createInstanceOfSchema = createInstanceOfSchema;
+const zod_1 = require("zod");
+/**
+ * Track metadata for schema comparison in tests and documentation.
+ * Only required for schemas that can't be compared out of the box,
+ * like custom schemas or instanceof schemas.
+ */
+exports.stackObjectRegistry = zod_1.z.registry();
+/**
+ * Creates a Zod schema for stack objects that have a stackObjectType property.
+ * This is a helper to reduce boilerplate when creating custom stack object schemas.
+ * It also ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.custom() directly for stack objects.
+ *
+ * @example
+ * ```ts
+ * interface StackEmail {
+ *   stackObjectType: "email";
+ *   to: string;
+ *   subject: string;
+ *   body: string;
+ * }
+ *
+ * const stackEmailSchema = createStackObjectSchema<StackEmail>("email");
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(email:${stackEmailSchema} -- sent:${z.boolean()})`, "Send email")
+ * async SEND(email: StackEmail): Promise<boolean> { ... }
+ * ```
+ */
+function createStackObjectSchema(stackObjectType, errorMessage) {
+    const schema = zod_1.z.custom((maybeStackObject) => maybeStackObject?.stackObjectType === stackObjectType, errorMessage ?? `expected ${stackObjectType} stackObjectType`);
+    // Register schema with metadata
+    exports.stackObjectRegistry.add(schema, {
+        objectType: "stackObject",
+        stackObjectType,
+    });
+    return schema;
+}
+/**
+ * Creates a Zod instanceof schema with automatic metadata registration.
+ * This ensures the schema is registered in stackObjectRegistry, which enables
+ * proper type string generation in stack effects.
+ *
+ * Use this instead of z.instanceof() directly.
+ *
+ * @example
+ * ```ts
+ * import { Temporal } from "temporal-polyfill";
+ *
+ * const plainDateSchema = createInstanceOfSchema(Temporal.PlainDate);
+ *
+ * // Use in stack effect:
+ * @ForthicWord(se`(date:${plainDateSchema} -- formatted:${z.string()})`, "Format date")
+ * async FORMAT(date: Temporal.PlainDate): Promise<string> { ... }
+ * ```
+ */
+function createInstanceOfSchema(ClassToSchematize, 
+/** If not passed, falls back to class.name */
+className) {
+    const schema = zod_1.z.instanceof(ClassToSchematize);
+    // Register schema with metadata
+    const resolvedClassName = className ?? ClassToSchematize.name;
+    exports.stackObjectRegistry.add(schema, {
+        objectType: "class",
+        OriginalClass: ClassToSchematize,
+        className: resolvedClassName,
+    });
+    return schema;
+}
+//# sourceMappingURL=schemaUtils.js.map

package/dist/cjs/forthic/decorators/schemaUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaUtils.js","sourceRoot":"","sources":["../../../../src/forthic/decorators/schemaUtils.ts"],"names":[],"mappings":";;;AAkDA,0DAgBC;AAoBD,wDAgBC;AAtGD,6BAAwB;AAmBxB;;;;GAIG;AACU,QAAA,mBAAmB,GAAG,OAAC,CAAC,QAAQ,EAAuB,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,uBAAuB,CACrC,eAAuB,EACvB,YAAqB;IAErB,MAAM,MAAM,GAAG,OAAC,CAAC,MAAM,CACrB,CAAC,gBAAgB,EAAE,EAAE,CAAE,gBAAkC,EAAE,eAAe,KAAK,eAAe,EAC9F,YAAY,IAAI,YAAY,eAAe,kBAAkB,CAC9D,CAAC;IAEF,gCAAgC;IAChC,2BAAmB,CAAC,GAAG,CAAC,MAAM,EAAE;QAC9B,UAAU,EAAE,aAAa;QACzB,eAAe;KAChB,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,sBAAsB,CACpC,iBAAoB;AACpB,8CAA8C;AAC9C,SAAkB;IAElB,MAAM,MAAM,GAAG,OAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE/C,gCAAgC;IAChC,MAAM,iBAAiB,GAAG,SAAS,IAAI,iBAAiB,CAAC,IAAI,CAAC;IAC9D,2BAAmB,CAAC,GAAG,CAAC,MAAM,EAAE;QAC9B,UAAU,EAAE,OAAO;QACnB,aAAa,EAAE,iBAAiB;QAChC,SAAS,EAAE,iBAAiB;KAC7B,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cjs/forthic/decorators/stackEffect.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import type { util as zodUtil } from "zod/v4/core";
+/**
+ * Map the set of Zod types to the strings we use in Forthic stack effects.
+ * Uses Zod's internal def.type for comprehensive type detection.
+ */
+export declare const mapZodToStackEffectType: (zodType: z.ZodTypeAny) => string;
+type InferTupleTypes<T extends zodUtil.TupleItems> = {
+    [K in keyof T]: T[K] extends z.ZodTypeAny ? z.infer<T[K]> : never;
+};
+/**
+ * Represents a type-safe stack effect with Zod schemas for validation.
+ *
+ * @template Args - Tuple of Zod schemas for input parameters
+ * @template Return - Zod schema for the return type
+ */
+export type TaggedStackEffect<Args extends zodUtil.TupleItems, Return extends z.core.$ZodFunctionOut = z.core.$ZodFunctionOut> = {
+    /** The human-readable stack effect string (e.g., "( a:number b:string -- result:string )") */
+    stackEffect: string;
+    /** Zod schemas for runtime validation */
+    schema: {
+        inputSchemas: z.ZodTypeAny[];
+        outputSchema: z.ZodTypeAny;
+    };
+    /**
+     * Phantom property to convey the expected function signature, constructed from the input + output types.
+     * DO NOT USE AT RUNTIME - it's only used for type inference.
+     */
+    _implType: (...args: InferTupleTypes<Args>) => Promise<z.infer<Return>>;
+};
+/**
+ * Tagged template literal for stack effects. Use with the @ForthicWord decorator to
+ * create a type-safe stack effect.
+ *
+ * @example
+ * ```ts
+ * // Type-safe stack effect with Zod validation
+ * @ForthicWord(se`(a:${z.number()} b:${z.string()} -- result:${z.string()})`, "Concatenate number and string")
+ * async CONCAT(a: number, b: string): Promise<string> {
+ *   return `${a}${b}`;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No parameters, returns string
+ * @ForthicWord(se`( -- message:${z.string()})`, "Get greeting")
+ * async GREET(): Promise<string> {
+ *   return "Hello!";
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Takes string, no return (void)
+ * @ForthicWord(se`(input:${z.string()} -- ${z.void()})`, "Log to console")
+ * async LOG(input: string): Promise<void> {
+ *   console.log(input);
+ * }
+ * ```
+ */
+export declare const se: <Args extends zodUtil.TupleItems, Return extends z.core.$ZodFunctionOut>(template: TemplateStringsArray, ...values: [...Args, Return]) => TaggedStackEffect<Args, Return>;
+export {};

package/dist/cjs/forthic/decorators/stackEffect.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.se = exports.mapZodToStackEffectType = void 0;
+const schemaUtils_js_1 = require("./schemaUtils.js");
+/**
+ * Map the set of Zod types to the strings we use in Forthic stack effects.
+ * Uses Zod's internal def.type for comprehensive type detection.
+ */
+const mapZodToStackEffectType = (zodType) => {
+    const def = zodType.def;
+    switch (def.type) {
+        case "string":
+            return "string";
+        case "int":
+        case "bigint":
+            return "number";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "undefined":
+        case "void":
+            return "";
+        case "date":
+            return "date";
+        case "symbol":
+            return "symbol";
+        case "object": {
+            const objectDef = def;
+            const objectShape = objectDef.shape;
+            // Get all property types
+            const properties = Object.entries(objectShape).map(([key, fieldSchema]) => {
+                const fieldType = (0, exports.mapZodToStackEffectType)(fieldSchema);
+                return `${key}: ${fieldType}`;
+            });
+            // Return formatted object type
+            return properties.length > 0 ? `{ ${properties.join(", ")} }` : "{}";
+        }
+        case "literal": {
+            const literalDef = def;
+            const value = literalDef.values[0];
+            // Quote string literals
+            return typeof value === "string" ? `"${value}"` : String(value);
+        }
+        case "enum": {
+            const enumDef = def;
+            const enumEntries = Object.values(enumDef.entries);
+            // Return union of quoted values - zod enums are always strings
+            return enumEntries.map((entry) => `"${entry}"`).join("|");
+        }
+        case "optional": {
+            const optionalDef = def;
+            const innerType = (0, exports.mapZodToStackEffectType)(optionalDef.innerType);
+            // Optional is a union with undefined
+            return innerType ? `${innerType}|undefined` : "undefined";
+        }
+        case "nullable": {
+            const nullableDef = def;
+            const innerType = (0, exports.mapZodToStackEffectType)(nullableDef.innerType);
+            // Nullable is a union with null
+            return innerType ? `${innerType}|null` : "null";
+        }
+        case "union": {
+            const unionDef = def;
+            const unionOptions = unionDef.options;
+            // Recursively get types for all union options
+            const optionTypes = unionOptions.map((option) => (0, exports.mapZodToStackEffectType)(option));
+            // Dedupe
+            return [...new Set(optionTypes)].join("|");
+        }
+        case "tuple": {
+            const tupleDef = def;
+            const tupleItems = tupleDef.items;
+            const elementTypes = tupleItems.map((item) => (0, exports.mapZodToStackEffectType)(item));
+            return `[${elementTypes.join(", ")}]`;
+        }
+        case "array": {
+            const arrayDef = def;
+            const elementType = (0, exports.mapZodToStackEffectType)(arrayDef.element);
+            // If the element is a union (contains "|") but not already an array type (doesn't end with "]"),
+            // wrap it in parentheses
+            const needsParens = elementType.includes("|") && !elementType.endsWith("]");
+            const wrappedType = needsParens ? `(${elementType})` : elementType;
+            return `${wrappedType}[]`;
+        }
+        case "custom": {
+            const metadata = schemaUtils_js_1.stackObjectRegistry.get(zodType);
+            if (!metadata) {
+                throw new Error(`Custom schema found without stack object registry entry. Consider using createStackObjectSchema or createInstanceOfSchema or manually registering the schema.`);
+            }
+            return metadata.stackObjectType ?? metadata.className ?? "object";
+        }
+        case "any":
+            return "any";
+        case "record":
+        case "function":
+        case "promise":
+        case "map":
+        case "set":
+        case "lazy":
+        case "never":
+        case "unknown":
+        case "file":
+        case "nonoptional":
+        case "success":
+        case "transform":
+        case "prefault":
+        case "nan":
+        case "pipe":
+        case "template_literal":
+        case "intersection":
+        case "catch":
+        case "default":
+        case "readonly":
+            // Unsupported types - throw error to ensure we handle everything
+            throw new Error(`Stack effect string generation not supported for type: "${def.type}" - you may either update mapZodToStackEffectType or use a simpler type (e.g. use createStackObjectSchema)`);
+        default:
+            throw new Error(`Unknown type: "${def.type}". You either need to update mapZodToStackEffectType, or zod is doing something unexpected.`);
+    }
+};
+exports.mapZodToStackEffectType = mapZodToStackEffectType;
+/**
+ * Tagged template literal for stack effects. Use with the @ForthicWord decorator to
+ * create a type-safe stack effect.
+ *
+ * @example
+ * ```ts
+ * // Type-safe stack effect with Zod validation
+ * @ForthicWord(se`(a:${z.number()} b:${z.string()} -- result:${z.string()})`, "Concatenate number and string")
+ * async CONCAT(a: number, b: string): Promise<string> {
+ *   return `${a}${b}`;
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // No parameters, returns string
+ * @ForthicWord(se`( -- message:${z.string()})`, "Get greeting")
+ * async GREET(): Promise<string> {
+ *   return "Hello!";
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Takes string, no return (void)
+ * @ForthicWord(se`(input:${z.string()} -- ${z.void()})`, "Log to console")
+ * async LOG(input: string): Promise<void> {
+ *   console.log(input);
+ * }
+ * ```
+ */
+const se = (template, ...values) => {
+    const stackEffectTypes = values.map((value) => (0, exports.mapZodToStackEffectType)(value));
+    // Outputs the template string as if it weren't tagged, e.g. "( a:string b:number -- c:number )"
+    const parts = [];
+    for (let i = 0; i < template.length; i++) {
+        parts.push(template[i]);
+        if (i < stackEffectTypes.length) {
+            parts.push(stackEffectTypes[i]);
+        }
+    }
+    const outStr = parts.join("");
+    const taggedStackEffect = {
+        stackEffect: outStr,
+        schema: {
+            inputSchemas: values.slice(0, -1),
+            outputSchema: values[values.length - 1],
+        },
+        _implType: async () => {
+            throw new Error("This function should not be called at runtime, it's only used for type inference");
+        },
+    };
+    return taggedStackEffect;
+};
+exports.se = se;
+//# sourceMappingURL=stackEffect.js.map

package/dist/cjs/forthic/decorators/stackEffect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackEffect.js","sourceRoot":"","sources":["../../../../src/forthic/decorators/stackEffect.ts"],"names":[],"mappings":"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"}

package/dist/cjs/forthic/errors.d.ts

@@ -15,6 +15,7 @@ export declare class ForthicError extends Error {
     getError(): Error;
     getForthic(): string;
     getNote(): string;
+    getMessage(): string;
 }
 export declare class UnknownWordError extends ForthicError {
     private word;
@@ -26,6 +27,7 @@ export declare class WordExecutionError extends ForthicError {
     private definition_location?;
     constructor(message: string, error: Error, call_location?: CodeLocationData, definition_location?: CodeLocationData);
     getError(): Error;
+    getRootError(): Error;
     getDefinitionLocation(): CodeLocationData | undefined;
 }
 export declare class MissingSemicolonError extends ForthicError {

package/dist/cjs/forthic/errors.js

@@ -19,7 +19,7 @@ class ForthicError extends Error {
         }
     }
     getDescription() {
-        throw new Error("Not implemented");
+        return this.note;
     }
     getError() {
         return this;
@@ -30,6 +30,9 @@ class ForthicError extends Error {
     getNote() {
         return this.note;
     }
+    getMessage() {
+        return this.note;
+    }
 }
 exports.ForthicError = ForthicError;
 class UnknownWordError extends ForthicError {
@@ -49,13 +52,21 @@ class WordExecutionError extends ForthicError {
     innerError;
     definition_location;
     constructor(message, error, call_location, definition_location) {
-        super("", message, call_location);
+        // Pass the error as cause to maintain compatibility with code that checks .cause
+        super("", message, call_location, error);
         this.innerError = error;
         this.definition_location = definition_location;
     }
     getError() {
         return this.innerError;
     }
+    getRootError() {
+        let current = this.innerError;
+        while (current.cause instanceof Error) {
+            current = current.cause;
+        }
+        return current;
+    }
     getDefinitionLocation() {
         return this.definition_location;
     }

package/dist/cjs/forthic/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/forthic/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/forthic/errors.ts"],"names":[],"mappings":"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"}

package/dist/cjs/forthic/interpreter.d.ts

@@ -81,6 +81,16 @@ export declare class Interpreter {
     execute_with_recovery(numAttempts?: number): Promise<number>;
     continue(): Promise<void>;
     run_with_tokenizer(tokenizer: Tokenizer): Promise<boolean>;
+    /**
+     * Execute a sequence of word tokens with deferred word lookup.
+     * This resolves words at execution time (not parse time) to support
+     * dynamically defined words (e.g., words defined by LOAD).
+     *
+     * Words are looked up and executed ONE AT A TIME to ensure that
+     * words defined during execution (e.g., by LOAD) are available
+     * for subsequent words in the same batch.
+     */
+    private executeBatchedWordTokens;
     /**
      * Execute a sequence of words with batching optimization
      */
@@ -107,7 +117,7 @@ export declare class Interpreter {
     private register_standard_literals;
     /**
      * Register a custom literal handler
-     * Handlers are checked in registration order
+     * New handlers are added first so they can override existing ones
      */
     register_literal_handler(handler: LiteralHandler): void;
     /**

package/dist/cjs/forthic/interpreter.js

@@ -293,30 +293,30 @@ class Interpreter {
         return;
     }
     async run_with_tokenizer(tokenizer) {
-        // Collect all words first for batching optimization
-        const words = [];
+        // Collect word tokens first for batching optimization
+        // We store tokens (not resolved Words) to defer word lookup until execution time.
+        // This allows dynamically defined words (e.g., from LOAD) to be found.
+        const wordTokens = [];
         let token;
         do {
             this.previous_token = token;
             token = tokenizer.next_token();
-            // For word tokens, collect them instead of executing immediately
+            // For word tokens, collect the token (defer word lookup until execution)
             if (token.type === tokenizer_js_1.TokenType.WORD && !this.is_compiling) {
-                const word = this.find_word(token.string);
-                word.set_location(token.location);
-                words.push(word);
+                wordTokens.push(token);
             }
             else {
                 // For non-word tokens, execute any collected words first, then handle the token
-                if (words.length > 0) {
-                    await this.executeBatchedWords(words);
-                    words.length = 0; // Clear the array
+                if (wordTokens.length > 0) {
+                    await this.executeBatchedWordTokens(wordTokens);
+                    wordTokens.length = 0; // Clear the array
                 }
                 await this.handle_token(token);
             }
             if (token.type === tokenizer_js_1.TokenType.EOS) {
                 // Execute any remaining words
-                if (words.length > 0) {
-                    await this.executeBatchedWords(words);
+                if (wordTokens.length > 0) {
+                    await this.executeBatchedWordTokens(wordTokens);
                 }
                 break;
             }
@@ -324,6 +324,25 @@ class Interpreter {
         } while (true);
         return true; // Done executing
     }
+    /**
+     * Execute a sequence of word tokens with deferred word lookup.
+     * This resolves words at execution time (not parse time) to support
+     * dynamically defined words (e.g., words defined by LOAD).
+     *
+     * Words are looked up and executed ONE AT A TIME to ensure that
+     * words defined during execution (e.g., by LOAD) are available
+     * for subsequent words in the same batch.
+     */
+    async executeBatchedWordTokens(tokens) {
+        // Look up and execute each word one at a time
+        // This ensures words defined during execution are available for later words
+        for (const token of tokens) {
+            const word = this.find_word(token.string);
+            word.set_location(token.location);
+            this.count_word(word);
+            await word.execute(this);
+        }
+    }
     /**
      * Execute a sequence of words with batching optimization
      */
@@ -346,7 +365,24 @@ class Interpreter {
                 // Execute local words one by one
                 for (const word of batch.words) {
                     this.count_word(word);
-                    await word.execute(this);
+                    try {
+                        await word.execute(this);
+                    }
+                    catch (e) {
+                        // Don't wrap IntentionalStopError - it's a control-flow mechanism for debugging
+                        if (e instanceof errors_js_1.IntentionalStopError) {
+                            throw e;
+                        }
+                        // Don't wrap ForthicError subclasses - they already have location context
+                        if (e instanceof errors_js_1.ForthicError) {
+                            throw e;
+                        }
+                        // Wrap generic errors in WordExecutionError to add location context
+                        if (e instanceof Error) {
+                            throw new errors_js_1.WordExecutionError(e.message, e, this.get_tokenizer()?.get_token_location(), word.get_location() || undefined);
+                        }
+                        throw e;
+                    }
                 }
             }
             else {
@@ -494,10 +530,10 @@ class Interpreter {
     }
     /**
      * Register a custom literal handler
-     * Handlers are checked in registration order
+     * New handlers are added first so they can override existing ones
      */
     register_literal_handler(handler) {
-        this.literal_handlers.push(handler);
+        this.literal_handlers.unshift(handler);
     }
     /**
      * Unregister a literal handler