add support to create prototypey lexicon fromJSON with cli support (#26)

* initial implementation with tests for fromJson

* cli to generate from json and updated docs

* include changeset

* fix lint and format

.changeset/eleven-steaks-search.md

···
+---
+"prototypey": minor
+---
+
+generate prototypey lexicon utils from json definitions

packages/prototypey/README.md

···
 prototypey gen-emit ./lexicons ./src/lexicons/**/*.ts
 ```
 
-### Typical Workflow
+#### `gen-from-json` - Generate TypeScript from JSON schemas
+
+```bash
+prototypey gen-from-json <outdir> <sources...>
+```
+
+Generates TypeScript files from JSON lexicon schemas using the `fromJSON` helper. This is useful when you have existing lexicon JSON files and want to work with them in TypeScript with full type inference.
+
+**Example:**
+
+```bash
+prototypey gen-from-json ./src/lexicons ./lexicons/**/*.json
+```
+
+This will create TypeScript files that export typed lexicon objects:
+
+```ts
+// Generated file: src/lexicons/app.bsky.feed.post.ts
+import { fromJSON } from "prototypey";
+
+export const appBskyFeedPost = fromJSON({
+  // ... lexicon JSON
+});
+```
+
+### Typical Workflows
+
+#### TypeScript-first workflow
 
 1. Author lexicons in TypeScript using the library
 2. Emit JSON schemas with `gen-emit` for runtime validation
···
 npm run lexicon:emit
 ```
 
+#### JSON-first workflow
+
+1. Start with JSON lexicon schemas (e.g., from atproto)
+2. Generate TypeScript with `gen-from-json` for type-safe access
+
+**Recommended:** Add as a script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lexicon:import": "prototypey gen-from-json ./src/lexicons ./lexicons/**/*.json"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run lexicon:import
+```
+
 ## State of the Project
 
 **Done:**
···
 - Inferrance of valid type from full lexicon definition
   - the really cool part of this is that it fills in the refs from the defs all at the type level
 - `lx.lexicon(...).validate(data)` for validating data using `@atproto/lexicon` and your lexicon definitions
-
-**TODO/In Progress:**
-
-- Library art! Please reach out if you'd be willing to contribute some drawings or anything!
-- Add CLI support for inferring and validating from json as the starting point
+- `fromJSON()` helper for creating lexicons directly from JSON objects with full type inference
 
-Please give any and all feedback. I've not really written many lexicons much myself yet, so this project is at a point of "well I think this makes sense" 😂. Both the [issues page](https://github.com/tylersayshi/prototypey/issues) and [discussions](https://github.com/tylersayshi/prototypey/discussions) are open and ready for y'all 🙂.
+Please give any and all feedback. I've not really written many lexicons much myself yet, so this project is at a point of "well I think this makes sense". Both the [issues page](https://github.com/tylersayshi/prototypey/issues) and [discussions](https://github.com/tylersayshi/prototypey/discussions) are open and ready for y'all 🙂.
 
----
+**Call For Contribution:**
 
-> 💝 This package was templated with
-> [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app)
-> using the [Bingo framework](https://create.bingo).
+- We need library art! Please reach out if you'd be willing to contribute some drawings or anything :)

packages/prototypey/cli/gen-from-json.ts

···
+import { glob } from "tinyglobby";
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { join, dirname, basename } from "node:path";
+
+interface LexiconJSON {
+	lexicon: number;
+	id: string;
+	defs: Record<string, unknown>;
+}
+
+/**
+ * Converts a lexicon ID to a valid TypeScript export name
+ * e.g., "app.bsky.feed.post" -> "appBskyFeedPost"
+ * "com.atproto.repo.createRecord" -> "comAtprotoRepoCreateRecord"
+ */
+function lexiconIdToExportName(id: string): string {
+	// Split by dots and handle camelCase conversion
+	const parts = id.split(".");
+
+	// For the first part (e.g., "app", "com"), keep it lowercase
+	// For subsequent parts, capitalize the first letter of each word
+	// But preserve any existing camelCase within parts
+	return parts
+		.map((part, index) => {
+			if (index === 0) return part;
+			// Capitalize first letter of the part
+			return part.charAt(0).toUpperCase() + part.slice(1);
+		})
+		.join("");
+}
+
+export async function genFromJSON(
+	outdir: string,
+	sources: string | string[],
+): Promise<void> {
+	try {
+		const sourcePatterns = Array.isArray(sources) ? sources : [sources];
+
+		// Find all JSON files matching the patterns
+		const jsonFiles = await glob(sourcePatterns, {
+			absolute: true,
+			onlyFiles: true,
+		});
+
+		if (jsonFiles.length === 0) {
+			console.log("No JSON files found matching patterns:", sourcePatterns);
+			return;
+		}
+
+		console.log(`Found ${String(jsonFiles.length)} JSON file(s)`);
+
+		// Ensure output directory exists
+		await mkdir(outdir, { recursive: true });
+
+		// Process each JSON file
+		for (const jsonPath of jsonFiles) {
+			await processJSONFile(jsonPath, outdir);
+		}
+
+		console.log(`\nGenerated TypeScript files in ${outdir}`);
+	} catch (error) {
+		console.error("Error generating TypeScript from JSON:", error);
+		process.exit(1);
+	}
+}
+
+async function processJSONFile(
+	jsonPath: string,
+	outdir: string,
+): Promise<void> {
+	try {
+		// Read and parse the JSON file
+		const content = await readFile(jsonPath, "utf-8");
+		const lexiconJSON = JSON.parse(content);
+
+		// Validate it's a lexicon
+		if (
+			!lexiconJSON.lexicon ||
+			!lexiconJSON.id ||
+			!lexiconJSON.defs ||
+			typeof lexiconJSON.defs !== "object"
+		) {
+			console.warn(`  ⚠ ${jsonPath}: Not a valid lexicon JSON`);
+			return;
+		}
+
+		const { id } = lexiconJSON as LexiconJSON;
+		const exportName = lexiconIdToExportName(id);
+
+		// Generate TypeScript content
+		const tsContent = `import { fromJSON } from "prototypey";
+
+export const ${exportName} = fromJSON(${JSON.stringify(lexiconJSON, null, "\t")});
+`;
+
+		// Determine output path - use same structure but in outdir
+		const outputFileName = `${basename(jsonPath, ".json")}.ts`;
+		const outputPath = join(outdir, outputFileName);
+
+		// Ensure output directory exists
+		await mkdir(dirname(outputPath), { recursive: true });
+
+		// Write the TypeScript file
+		await writeFile(outputPath, tsContent, "utf-8");
+
+		console.log(`  ✓ ${id} -> ${outputFileName}`);
+	} catch (error) {
+		console.error(`  ✗ Error processing ${jsonPath}:`, error);
+		throw error;
+	}
+}

packages/prototypey/cli/main.ts

···
 
 import sade from "sade";
 import { genEmit } from "./gen-emit.ts";
+import { genFromJSON } from "./gen-from-json.ts";
 import pkg from "../package.json" with { type: "json" };
 
 const prog = sade("prototypey");
···
 	.describe("Emit JSON lexicon schemas from authored TypeScript")
 	.example("gen-emit ./lexicons ./src/lexicons/**/*.ts")
 	.action(genEmit);
+
+prog
+	.command("gen-from-json <outdir> <sources...>")
+	.describe("Generate TypeScript files from JSON lexicon schemas")
+	.example("gen-from-json ./src/lexicons ./lexicons/**/*.json")
+	.action(genFromJSON);
 
 prog.parse(process.argv);

packages/prototypey/cli/tests/gen-from-json.test.ts

···
+import { expect, test, describe, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { genFromJSON } from "../gen-from-json.ts";
+
+describe("genFromJSON", () => {
+	let testDir: string;
+	let outDir: string;
+
+	beforeEach(async () => {
+		// Create a temporary directory for test files
+		testDir = join(tmpdir(), `prototypey-test-import-${String(Date.now())}`);
+		outDir = join(testDir, "output");
+		await mkdir(testDir, { recursive: true });
+		await mkdir(outDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		// Clean up test directory
+		await rm(testDir, { recursive: true, force: true });
+	});
+
+	test("generates TypeScript from a simple JSON lexicon", async () => {
+		// Create a test JSON lexicon file
+		const jsonFile = join(testDir, "app.bsky.actor.profile.json");
+		const lexiconJSON = {
+			lexicon: 1,
+			id: "app.bsky.actor.profile",
+			defs: {
+				main: {
+					type: "record",
+					key: "self",
+					record: {
+						type: "object",
+						properties: {
+							displayName: {
+								type: "string",
+								maxLength: 64,
+								maxGraphemes: 64,
+							},
+							description: {
+								type: "string",
+								maxLength: 256,
+								maxGraphemes: 256,
+							},
+						},
+					},
+				},
+			},
+		};
+
+		await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+
+		// Run the from-json command
+		await genFromJSON(outDir, jsonFile);
+
+		// Read the generated TypeScript file
+		const outputFile = join(outDir, "app.bsky.actor.profile.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		// Verify the structure
+		expect(content).toContain('import { fromJSON } from "prototypey"');
+		expect(content).toContain("export const appBskyActorProfile = fromJSON(");
+		expect(content).toContain('"id": "app.bsky.actor.profile"');
+		expect(content).toContain('"lexicon": 1');
+
+		// Verify it can be parsed as JSON within the call
+		const jsonMatch = content.match(/fromJSON\(([\s\S]+)\);/);
+		expect(jsonMatch).toBeTruthy();
+		if (jsonMatch) {
+			const parsedJSON = JSON.parse(jsonMatch[1]);
+			expect(parsedJSON).toEqual(lexiconJSON);
+		}
+	});
+
+	test("handles multiple JSON files with glob pattern", async () => {
+		// Create multiple test JSON files
+		const lexicons = join(testDir, "lexicons");
+		await mkdir(lexicons, { recursive: true });
+
+		const profileJSON = {
+			lexicon: 1,
+			id: "app.bsky.actor.profile",
+			defs: {
+				main: {
+					type: "record",
+					key: "self",
+					record: { type: "object", properties: {} },
+				},
+			},
+		};
+
+		const postJSON = {
+			lexicon: 1,
+			id: "app.bsky.feed.post",
+			defs: {
+				main: {
+					type: "record",
+					key: "tid",
+					record: { type: "object", properties: {} },
+				},
+			},
+		};
+
+		await writeFile(
+			join(lexicons, "app.bsky.actor.profile.json"),
+			JSON.stringify(profileJSON, null, 2),
+		);
+		await writeFile(
+			join(lexicons, "app.bsky.feed.post.json"),
+			JSON.stringify(postJSON, null, 2),
+		);
+
+		// Run with glob pattern
+		await genFromJSON(outDir, `${lexicons}/*.json`);
+
+		// Verify both files were created
+		const profileTS = await readFile(
+			join(outDir, "app.bsky.actor.profile.ts"),
+			"utf-8",
+		);
+		const postTS = await readFile(
+			join(outDir, "app.bsky.feed.post.ts"),
+			"utf-8",
+		);
+
+		expect(profileTS).toContain("appBskyActorProfile");
+		expect(postTS).toContain("appBskyFeedPost");
+	});
+
+	test("generates correct export names from lexicon IDs", async () => {
+		const testCases = [
+			{ id: "app.bsky.feed.post", expectedName: "appBskyFeedPost" },
+			{
+				id: "com.atproto.repo.createRecord",
+				expectedName: "comAtprotoRepoCreateRecord",
+			},
+			{ id: "app.bsky.actor.profile", expectedName: "appBskyActorProfile" },
+			{ id: "simple", expectedName: "simple" },
+		];
+
+		for (const { id, expectedName } of testCases) {
+			const jsonFile = join(testDir, `${id}.json`);
+			const lexiconJSON = {
+				lexicon: 1,
+				id,
+				defs: { main: { type: "object", properties: {} } },
+			};
+
+			await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+			await genFromJSON(outDir, jsonFile);
+
+			const outputFile = join(outDir, `${id}.ts`);
+			const content = await readFile(outputFile, "utf-8");
+
+			expect(content).toContain(`export const ${expectedName} = fromJSON(`);
+		}
+	});
+
+	test("generates TypeScript from query endpoint JSON", async () => {
+		const jsonFile = join(testDir, "app.bsky.feed.searchPosts.json");
+		const lexiconJSON = {
+			lexicon: 1,
+			id: "app.bsky.feed.searchPosts",
+			defs: {
+				main: {
+					type: "query",
+					description: "Find posts matching search criteria",
+					parameters: {
+						type: "params",
+						properties: {
+							q: { type: "string", required: true },
+							limit: { type: "integer", minimum: 1, maximum: 100, default: 25 },
+							cursor: { type: "string" },
+						},
+						required: ["q"],
+					},
+					output: {
+						encoding: "application/json",
+						schema: {
+							type: "object",
+							properties: {
+								cursor: { type: "string" },
+								posts: {
+									type: "array",
+									items: { type: "ref", ref: "app.bsky.feed.defs#postView" },
+									required: true,
+								},
+							},
+							required: ["posts"],
+						},
+					},
+				},
+			},
+		};
+
+		await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+		await genFromJSON(outDir, jsonFile);
+
+		const outputFile = join(outDir, "app.bsky.feed.searchPosts.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		expect(content).toContain("appBskyFeedSearchPosts");
+		expect(content).toContain('"type": "query"');
+		expect(content).toContain("Find posts matching search criteria");
+	});
+
+	test("generates TypeScript from procedure endpoint JSON", async () => {
+		const jsonFile = join(testDir, "com.atproto.repo.createRecord.json");
+		const lexiconJSON = {
+			lexicon: 1,
+			id: "com.atproto.repo.createRecord",
+			defs: {
+				main: {
+					type: "procedure",
+					description: "Create a record",
+					input: {
+						encoding: "application/json",
+						schema: {
+							type: "object",
+							properties: {
+								repo: { type: "string", required: true },
+								collection: { type: "string", required: true },
+								record: { type: "unknown", required: true },
+							},
+							required: ["repo", "collection", "record"],
+						},
+					},
+					output: {
+						encoding: "application/json",
+						schema: {
+							type: "object",
+							properties: {
+								uri: { type: "string", required: true },
+								cid: { type: "string", required: true },
+							},
+							required: ["uri", "cid"],
+						},
+					},
+				},
+			},
+		};
+
+		await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+		await genFromJSON(outDir, jsonFile);
+
+		const outputFile = join(outDir, "com.atproto.repo.createRecord.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		expect(content).toContain("comAtprotoRepoCreateRecord");
+		expect(content).toContain('"type": "procedure"');
+	});
+
+	test("generates TypeScript from subscription endpoint JSON", async () => {
+		const jsonFile = join(testDir, "com.atproto.sync.subscribeRepos.json");
+		const lexiconJSON = {
+			lexicon: 1,
+			id: "com.atproto.sync.subscribeRepos",
+			defs: {
+				main: {
+					type: "subscription",
+					description: "Repository event stream",
+					parameters: {
+						type: "params",
+						properties: {
+							cursor: { type: "integer" },
+						},
+					},
+					message: {
+						schema: {
+							type: "union",
+							refs: ["#commit", "#identity", "#account"],
+						},
+					},
+				},
+				commit: {
+					type: "object",
+					properties: {
+						seq: { type: "integer", required: true },
+						rebase: { type: "boolean", required: true },
+					},
+					required: ["seq", "rebase"],
+				},
+				identity: {
+					type: "object",
+					properties: {
+						seq: { type: "integer", required: true },
+						did: { type: "string", format: "did", required: true },
+					},
+					required: ["seq", "did"],
+				},
+				account: {
+					type: "object",
+					properties: {
+						seq: { type: "integer", required: true },
+						active: { type: "boolean", required: true },
+					},
+					required: ["seq", "active"],
+				},
+			},
+		};
+
+		await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+		await genFromJSON(outDir, jsonFile);
+
+		const outputFile = join(outDir, "com.atproto.sync.subscribeRepos.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		expect(content).toContain("comAtprotoSyncSubscribeRepos");
+		expect(content).toContain('"type": "subscription"');
+		expect(content).toContain("commit");
+		expect(content).toContain("identity");
+		expect(content).toContain("account");
+	});
+
+	test("generates TypeScript from complex namespace with refs and unions", async () => {
+		const jsonFile = join(testDir, "app.bsky.feed.defs.json");
+		const lexiconJSON = {
+			lexicon: 1,
+			id: "app.bsky.feed.defs",
+			defs: {
+				postView: {
+					type: "object",
+					properties: {
+						uri: { type: "string", format: "at-uri", required: true },
+						cid: { type: "string", format: "cid", required: true },
+						author: {
+							type: "ref",
+							ref: "app.bsky.actor.defs#profileViewBasic",
+							required: true,
+						},
+						embed: {
+							type: "union",
+							refs: ["app.bsky.embed.images#view", "app.bsky.embed.video#view"],
+						},
+						likeCount: { type: "integer", minimum: 0 },
+					},
+					required: ["uri", "cid", "author"],
+				},
+				requestLess: {
+					type: "token",
+					description: "Request less content like this",
+				},
+				requestMore: {
+					type: "token",
+					description: "Request more content like this",
+				},
+			},
+		};
+
+		await writeFile(jsonFile, JSON.stringify(lexiconJSON, null, 2));
+		await genFromJSON(outDir, jsonFile);
+
+		const outputFile = join(outDir, "app.bsky.feed.defs.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		expect(content).toContain("appBskyFeedDefs");
+		expect(content).toContain("postView");
+		expect(content).toContain("requestLess");
+		expect(content).toContain("requestMore");
+	});
+
+	test("handles invalid JSON gracefully", async () => {
+		const jsonFile = join(testDir, "invalid.json");
+		await writeFile(jsonFile, "{ this is not valid json }");
+
+		await expect(genFromJSON(outDir, jsonFile)).rejects.toThrow();
+	});
+
+	test("skips non-lexicon JSON files", async () => {
+		const jsonFile = join(testDir, "not-a-lexicon.json");
+		await writeFile(
+			jsonFile,
+			JSON.stringify({ someKey: "someValue" }, null, 2),
+		);
+
+		// Should not throw, just warn and skip
+		await genFromJSON(outDir, jsonFile);
+
+		// Verify no output file was created
+		const outputFiles = await readdir(outDir).catch(() => []);
+		expect(outputFiles.length).toBe(0);
+	});
+
+	test("round-trip: gen-emit then gen-from-json produces equivalent types", async () => {
+		// This is an integration test that verifies the round-trip works
+		const intermediateDir = join(testDir, "json");
+		await mkdir(intermediateDir, { recursive: true });
+
+		// First, create a simple TypeScript lexicon
+		const tsFile = join(testDir, "original.ts");
+		await writeFile(
+			tsFile,
+			`
+import { lx } from "prototypey";
+
+export const postSchema = lx.lexicon("app.bsky.feed.post", {
+	main: lx.record({
+		key: "tid",
+		record: lx.object({
+			text: lx.string({ maxLength: 300, required: true }),
+			createdAt: lx.string({ format: "datetime", required: true }),
+		}),
+	}),
+});
+`,
+		);
+
+		// Import gen-emit dynamically to use it
+		const { genEmit } = await import("../gen-emit.ts");
+
+		// Step 1: gen-emit to create JSON
+		await genEmit(intermediateDir, tsFile);
+
+		// Step 2: gen-from-json to create TypeScript from JSON
+		const jsonFile = join(intermediateDir, "app.bsky.feed.post.json");
+		await genFromJSON(outDir, jsonFile);
+
+		// Verify the output exists
+		const outputFile = join(outDir, "app.bsky.feed.post.ts");
+		const content = await readFile(outputFile, "utf-8");
+
+		expect(content).toContain("appBskyFeedPost");
+		expect(content).toContain('"id": "app.bsky.feed.post"');
+		expect(content).toContain('"type": "record"');
+	});
+});
+
+// Helper function that was missing from imports
+async function readdir(path: string): Promise<string[]> {
+	const { readdir: fsReaddir } = await import("node:fs/promises");
+	return fsReaddir(path);
+}

packages/prototypey/core/lib.ts

···
 		});
 	},
 };
+
+/** helper to pull lexicon from json directly */
+export function fromJSON<const Lex extends LexiconNamespace>(json: Lex) {
+	return lx.lexicon<Lex["id"], Lex["defs"]>(json.id, json.defs);
+}

packages/prototypey/core/main.ts

···
-export { lx } from "./lib.ts";
+export { lx, fromJSON } from "./lib.ts";
 export { type Infer } from "./infer.ts";

packages/prototypey/core/tests/from-json-infer.test.ts

···
+import { test } from "vitest";
+import { attest } from "@ark/attest";
+import { fromJSON } from "../lib.ts";
+
+test("fromJSON InferNS produces expected type shape", () => {
+	const exampleLexicon = fromJSON({
+		id: "com.example.post",
+		defs: {
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						text: { type: "string", required: true },
+						createdAt: { type: "string", required: true, format: "datetime" },
+						likes: { type: "integer" },
+						tags: { type: "array", items: { type: "string" }, maxLength: 5 },
+					},
+					required: ["text", "createdAt"],
+				},
+			},
+		},
+	});
+
+	// Type snapshot - this captures how types appear on hover
+	attest(exampleLexicon["~infer"]).type.toString.snap(`{
+  $type: "com.example.post"
+  tags?: string[] | undefined
+  likes?: number | undefined
+  createdAt: string
+  text: string
+}`);
+});
+
+test("fromJSON InferObject handles required fields", () => {
+	const schema = fromJSON({
+		id: "test",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					required: { type: "string", required: true },
+					optional: { type: "string" },
+				},
+				required: ["required"],
+			},
+		},
+	});
+
+	attest(schema["~infer"]).type.toString.snap(`{
+  $type: "test"
+  optional?: string | undefined
+  required: string
+}`);
+});
+
+test("fromJSON InferObject handles nullable fields", () => {
+	const schema = fromJSON({
+		id: "test",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					nullable: { type: "string", nullable: true, required: true },
+				},
+				required: ["nullable"],
+				nullable: ["nullable"],
+			},
+		},
+	});
+
+	attest(schema["~infer"]).type.toString.snap(
+		'{ $type: "test"; nullable: string | null }',
+	);
+});
+
+// ============================================================================
+// PRIMITIVE TYPES TESTS
+// ============================================================================
+
+test("fromJSON InferType handles string primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.string",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					simpleString: { type: "string" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.string"
+  simpleString?: string | undefined
+}`);
+});
+
+test("fromJSON InferType handles integer primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.integer",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					count: { type: "integer" },
+					age: { type: "integer", minimum: 0, maximum: 120 },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.integer"
+  count?: number | undefined
+  age?: number | undefined
+}`);
+});
+
+test("fromJSON InferType handles boolean primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.boolean",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					isActive: { type: "boolean" },
+					hasAccess: { type: "boolean", required: true },
+				},
+				required: ["hasAccess"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.boolean"
+  isActive?: boolean | undefined
+  hasAccess: boolean
+}`);
+});
+
+test("fromJSON InferType handles null primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.null",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					nullValue: { type: "null" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.null"
+  nullValue?: null | undefined
+}`);
+});
+
+test("fromJSON InferType handles unknown primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.unknown",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					metadata: { type: "unknown" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(
+		'{ $type: "test.unknown"; metadata?: unknown }',
+	);
+});
+
+test("fromJSON InferType handles bytes primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.bytes",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					data: { type: "bytes" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.bytes"
+  data?: Uint8Array<ArrayBufferLike> | undefined
+}`);
+});
+
+test("fromJSON InferType handles blob primitive", () => {
+	const lexicon = fromJSON({
+		id: "test.blob",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					image: {
+						type: "blob",
+						accept: ["image/png", "image/jpeg"],
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(
+		'{ $type: "test.blob"; image?: Blob | undefined }',
+	);
+});
+
+// ============================================================================
+// TOKEN TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferToken handles basic token without enum", () => {
+	const lexicon = fromJSON({
+		id: "test.token",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					symbol: { type: "token", description: "A symbolic value" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.token"
+  symbol?: string | undefined
+}`);
+});
+
+// ============================================================================
+// ARRAY TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferArray handles string arrays", () => {
+	const lexicon = fromJSON({
+		id: "test.array.string",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					tags: { type: "array", items: { type: "string" } },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.array.string"
+  tags?: string[] | undefined
+}`);
+});
+
+test("fromJSON InferArray handles integer arrays", () => {
+	const lexicon = fromJSON({
+		id: "test.array.integer",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					scores: {
+						type: "array",
+						items: { type: "integer" },
+						minLength: 1,
+						maxLength: 10,
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.array.integer"
+  scores?: number[] | undefined
+}`);
+});
+
+test("fromJSON InferArray handles boolean arrays", () => {
+	const lexicon = fromJSON({
+		id: "test.array.boolean",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					flags: { type: "array", items: { type: "boolean" } },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.array.boolean"
+  flags?: boolean[] | undefined
+}`);
+});
+
+test("fromJSON InferArray handles unknown arrays", () => {
+	const lexicon = fromJSON({
+		id: "test.array.unknown",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					items: { type: "array", items: { type: "unknown" } },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.array.unknown"
+  items?: unknown[] | undefined
+}`);
+});
+
+// ============================================================================
+// OBJECT PROPERTY COMBINATIONS
+// ============================================================================
+
+test("fromJSON InferObject handles mixed optional and required fields", () => {
+	const lexicon = fromJSON({
+		id: "test.mixed",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					id: { type: "string", required: true },
+					name: { type: "string", required: true },
+					email: { type: "string" },
+					age: { type: "integer" },
+				},
+				required: ["id", "name"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.mixed"
+  age?: number | undefined
+  email?: string | undefined
+  id: string
+  name: string
+}`);
+});
+
+test("fromJSON InferObject handles all optional fields", () => {
+	const lexicon = fromJSON({
+		id: "test.allOptional",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					field1: { type: "string" },
+					field2: { type: "integer" },
+					field3: { type: "boolean" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.allOptional"
+  field1?: string | undefined
+  field2?: number | undefined
+  field3?: boolean | undefined
+}`);
+});
+
+test("fromJSON InferObject handles all required fields", () => {
+	const lexicon = fromJSON({
+		id: "test.allRequired",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					field1: { type: "string", required: true },
+					field2: { type: "integer", required: true },
+					field3: { type: "boolean", required: true },
+				},
+				required: ["field1", "field2", "field3"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.allRequired"
+  field1: string
+  field2: number
+  field3: boolean
+}`);
+});
+
+// ============================================================================
+// NULLABLE FIELDS TESTS
+// ============================================================================
+
+test("fromJSON InferObject handles nullable optional field", () => {
+	const lexicon = fromJSON({
+		id: "test.nullableOptional",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					description: { type: "string", nullable: true },
+				},
+				nullable: ["description"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.nullableOptional"
+  description?: string | null | undefined
+}`);
+});
+
+test("fromJSON InferObject handles multiple nullable fields", () => {
+	const lexicon = fromJSON({
+		id: "test.multipleNullable",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					field1: { type: "string", nullable: true },
+					field2: { type: "integer", nullable: true },
+					field3: { type: "boolean", nullable: true },
+				},
+				nullable: ["field1", "field2", "field3"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.multipleNullable"
+  field1?: string | null | undefined
+  field2?: number | null | undefined
+  field3?: boolean | null | undefined
+}`);
+});
+
+test("fromJSON InferObject handles nullable and required field", () => {
+	const lexicon = fromJSON({
+		id: "test.nullableRequired",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					value: { type: "string", nullable: true, required: true },
+				},
+				required: ["value"],
+				nullable: ["value"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.nullableRequired"
+  value: string | null
+}`);
+});
+
+test("fromJSON InferObject handles mixed nullable, required, and optional", () => {
+	const lexicon = fromJSON({
+		id: "test.mixedNullable",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					requiredNullable: { type: "string", required: true, nullable: true },
+					optionalNullable: { type: "string", nullable: true },
+					required: { type: "string", required: true },
+					optional: { type: "string" },
+				},
+				required: ["requiredNullable", "required"],
+				nullable: ["requiredNullable", "optionalNullable"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.mixedNullable"
+  optional?: string | undefined
+  required: string
+  optionalNullable?: string | null | undefined
+  requiredNullable: string | null
+}`);
+});
+
+// ============================================================================
+// REF TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferRef handles basic reference", () => {
+	const lexicon = fromJSON({
+		id: "test.ref",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					post: { type: "ref", ref: "com.example.post" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.ref"
+  post?:
+    | { [x: string]: unknown; $type: "com.example.post" }
+    | undefined
+}`);
+});
+
+test("fromJSON InferRef handles required reference", () => {
+	const lexicon = fromJSON({
+		id: "test.refRequired",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					author: { type: "ref", ref: "com.example.user", required: true },
+				},
+				required: ["author"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.refRequired"
+  author: {
+    [x: string]: unknown
+    $type: "com.example.user"
+  }
+}`);
+});
+
+test("fromJSON InferRef handles nullable reference", () => {
+	const lexicon = fromJSON({
+		id: "test.refNullable",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					parent: { type: "ref", ref: "com.example.node", nullable: true },
+				},
+				nullable: ["parent"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.refNullable"
+  parent?:
+    | { [x: string]: unknown; $type: "com.example.node" }
+    | null
+    | undefined
+}`);
+});
+
+// ============================================================================
+// UNION TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferUnion handles basic union", () => {
+	const lexicon = fromJSON({
+		id: "test.union",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					content: {
+						type: "union",
+						refs: ["com.example.text", "com.example.image"],
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.union"
+  content?:
+    | { [x: string]: unknown; $type: "com.example.text" }
+    | { [x: string]: unknown; $type: "com.example.image" }
+    | undefined
+}`);
+});
+
+test("fromJSON InferUnion handles required union", () => {
+	const lexicon = fromJSON({
+		id: "test.unionRequired",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					media: {
+						type: "union",
+						refs: ["com.example.video", "com.example.audio"],
+						required: true,
+					},
+				},
+				required: ["media"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.unionRequired"
+  media:
+    | { [x: string]: unknown; $type: "com.example.video" }
+    | { [x: string]: unknown; $type: "com.example.audio" }
+}`);
+});
+
+test("fromJSON InferUnion handles union with many types", () => {
+	const lexicon = fromJSON({
+		id: "test.unionMultiple",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					attachment: {
+						type: "union",
+						refs: [
+							"com.example.image",
+							"com.example.video",
+							"com.example.audio",
+							"com.example.document",
+						],
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.unionMultiple"
+  attachment?:
+    | { [x: string]: unknown; $type: "com.example.image" }
+    | { [x: string]: unknown; $type: "com.example.video" }
+    | { [x: string]: unknown; $type: "com.example.audio" }
+    | {
+        [x: string]: unknown
+        $type: "com.example.document"
+      }
+    | undefined
+}`);
+});
+
+// ============================================================================
+// PARAMS TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferParams handles basic params", () => {
+	const lexicon = fromJSON({
+		id: "test.params",
+		defs: {
+			main: {
+				type: "params",
+				properties: {
+					limit: { type: "integer" },
+					offset: { type: "integer" },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.params"
+  limit?: number | undefined
+  offset?: number | undefined
+}`);
+});
+
+test("fromJSON InferParams handles required params", () => {
+	const lexicon = fromJSON({
+		id: "test.paramsRequired",
+		defs: {
+			main: {
+				type: "params",
+				properties: {
+					query: { type: "string", required: true },
+					limit: { type: "integer" },
+				},
+				required: ["query"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.paramsRequired"
+  limit?: number | undefined
+  query: string
+}`);
+});
+
+// ============================================================================
+// RECORD TYPE TESTS
+// ============================================================================
+
+test("fromJSON InferRecord handles record with object schema", () => {
+	const lexicon = fromJSON({
+		id: "test.record",
+		defs: {
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						title: { type: "string", required: true },
+						content: { type: "string", required: true },
+						published: { type: "boolean" },
+					},
+					required: ["title", "content"],
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.record"
+  published?: boolean | undefined
+  content: string
+  title: string
+}`);
+});
+
+// ============================================================================
+// NESTED OBJECTS TESTS
+// ============================================================================
+
+test("fromJSON InferObject handles nested objects", () => {
+	const lexicon = fromJSON({
+		id: "test.nested",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					user: {
+						type: "object",
+						properties: {
+							name: { type: "string", required: true },
+							email: { type: "string", required: true },
+						},
+						required: ["name", "email"],
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.nested"
+  user?: { name: string; email: string } | undefined
+}`);
+});
+
+test("fromJSON InferObject handles deeply nested objects", () => {
+	const lexicon = fromJSON({
+		id: "test.deepNested",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					data: {
+						type: "object",
+						properties: {
+							user: {
+								type: "object",
+								properties: {
+									profile: {
+										type: "object",
+										properties: {
+											name: { type: "string", required: true },
+										},
+										required: ["name"],
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.deepNested"
+  data?:
+    | {
+        user?:
+          | { profile?: { name: string } | undefined }
+          | undefined
+      }
+    | undefined
+}`);
+});
+
+// ============================================================================
+// NESTED ARRAYS TESTS
+// ============================================================================
+
+test("fromJSON InferArray handles arrays of objects", () => {
+	const lexicon = fromJSON({
+		id: "test.arrayOfObjects",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					users: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								id: { type: "string", required: true },
+								name: { type: "string", required: true },
+							},
+							required: ["id", "name"],
+						},
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.arrayOfObjects"
+  users?: { id: string; name: string }[] | undefined
+}`);
+});
+
+test("fromJSON InferArray handles arrays of arrays", () => {
+	const lexicon = fromJSON({
+		id: "test.nestedArrays",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					matrix: {
+						type: "array",
+						items: { type: "array", items: { type: "integer" } },
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.nestedArrays"
+  matrix?: number[][] | undefined
+}`);
+});
+
+test("fromJSON InferArray handles arrays of refs", () => {
+	const lexicon = fromJSON({
+		id: "test.arrayOfRefs",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					followers: {
+						type: "array",
+						items: { type: "ref", ref: "com.example.user" },
+					},
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.arrayOfRefs"
+  followers?:
+    | { [x: string]: unknown; $type: "com.example.user" }[]
+    | undefined
+}`);
+});
+
+// ============================================================================
+// COMPLEX NESTED STRUCTURES
+// ============================================================================
+
+test("fromJSON InferObject handles complex nested structure", () => {
+	const lexicon = fromJSON({
+		id: "test.complex",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					id: { type: "string", required: true },
+					author: {
+						type: "object",
+						properties: {
+							did: { type: "string", required: true, format: "did" },
+							handle: { type: "string", required: true, format: "handle" },
+							avatar: { type: "string" },
+						},
+						required: ["did", "handle"],
+					},
+					content: {
+						type: "union",
+						refs: ["com.example.text", "com.example.image"],
+					},
+					tags: { type: "array", items: { type: "string" }, maxLength: 10 },
+					metadata: {
+						type: "object",
+						properties: {
+							views: { type: "integer" },
+							likes: { type: "integer" },
+							shares: { type: "integer" },
+						},
+					},
+				},
+				required: ["id"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "test.complex"
+  tags?: string[] | undefined
+  content?:
+    | { [x: string]: unknown; $type: "com.example.text" }
+    | { [x: string]: unknown; $type: "com.example.image" }
+    | undefined
+  author?:
+    | {
+        avatar?: string | undefined
+        did: string
+        handle: string
+      }
+    | undefined
+  metadata?:
+    | {
+        likes?: number | undefined
+        views?: number | undefined
+        shares?: number | undefined
+      }
+    | undefined
+  id: string
+}`);
+});
+
+// ============================================================================
+// MULTIPLE DEFS IN NAMESPACE
+// ============================================================================
+
+test("fromJSON InferNS handles multiple defs in namespace", () => {
+	const lexicon = fromJSON({
+		id: "com.example.app",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+					email: { type: "string", required: true },
+				},
+				required: ["name", "email"],
+			},
+			post: {
+				type: "object",
+				properties: {
+					title: { type: "string", required: true },
+					content: { type: "string", required: true },
+				},
+				required: ["title", "content"],
+			},
+			comment: {
+				type: "object",
+				properties: {
+					text: { type: "string", required: true },
+					author: { type: "ref", ref: "com.example.user" },
+				},
+				required: ["text"],
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap("never");
+});
+
+test("fromJSON InferNS handles namespace with record and object defs", () => {
+	const lexicon = fromJSON({
+		id: "com.example.blog",
+		defs: {
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						title: { type: "string", required: true },
+						body: { type: "string", required: true },
+					},
+					required: ["title", "body"],
+				},
+			},
+			metadata: {
+				type: "object",
+				properties: {
+					category: { type: "string" },
+					tags: { type: "array", items: { type: "string" } },
+				},
+			},
+		},
+	});
+
+	attest(lexicon["~infer"]).type.toString.snap(`{
+  $type: "com.example.blog"
+  title: string
+  body: string
+}`);
+});
+
+// ============================================================================
+// LOCAL REF RESOLUTION TESTS
+// ============================================================================
+
+test("fromJSON Local ref resolution: resolves refs to actual types", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+					email: { type: "string", required: true },
+				},
+				required: ["name", "email"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					author: { type: "ref", ref: "#user", required: true },
+					content: { type: "string", required: true },
+				},
+				required: ["author", "content"],
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  content: string
+  author: { name: string; email: string; $type: "#user" }
+}`);
+});
+
+test("fromJSON Local ref resolution: refs in arrays", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+				},
+				required: ["name"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					users: { type: "array", items: { type: "ref", ref: "#user" } },
+				},
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  users?: { name: string; $type: "#user" }[] | undefined
+}`);
+});
+
+test("fromJSON Local ref resolution: refs in unions", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			text: {
+				type: "object",
+				properties: { content: { type: "string", required: true } },
+				required: ["content"],
+			},
+			image: {
+				type: "object",
+				properties: { url: { type: "string", required: true } },
+				required: ["url"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					embed: { type: "union", refs: ["#text", "#image"] },
+				},
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  embed?:
+    | { content: string; $type: "#text" }
+    | { url: string; $type: "#image" }
+    | undefined
+}`);
+});
+
+test("fromJSON Local ref resolution: nested refs", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			profile: {
+				type: "object",
+				properties: {
+					bio: { type: "string", required: true },
+				},
+				required: ["bio"],
+			},
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+					profile: { type: "ref", ref: "#profile", required: true },
+				},
+				required: ["name", "profile"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					author: { type: "ref", ref: "#user", required: true },
+				},
+				required: ["author"],
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  author: {
+    name: string
+    profile: { bio: string; $type: "#profile" }
+    $type: "#user"
+  }
+}`);
+});
+
+// ============================================================================
+// EDGE CASE TESTS
+// ============================================================================
+
+test("fromJSON Edge case: circular reference detection", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					value: { type: "string", required: true },
+					parent: { type: "ref", ref: "#main" },
+				},
+				required: ["value"],
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  parent?:
+    | {
+        parent?:
+          | "[Circular reference detected: #main]"
+          | undefined
+        value: string
+        $type: "#main"
+      }
+    | undefined
+  value: string
+}`);
+});
+
+test("fromJSON Edge case: circular reference between multiple types", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+					posts: { type: "array", items: { type: "ref", ref: "#post" } },
+				},
+				required: ["name"],
+			},
+			post: {
+				type: "object",
+				properties: {
+					title: { type: "string", required: true },
+					author: { type: "ref", ref: "#user", required: true },
+				},
+				required: ["title", "author"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					users: { type: "array", items: { type: "ref", ref: "#user" } },
+				},
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  users?:
+    | {
+        posts?:
+          | {
+              author: "[Circular reference detected: #user]"
+              title: string
+              $type: "#post"
+            }[]
+          | undefined
+        name: string
+        $type: "#user"
+      }[]
+    | undefined
+}`);
+});
+
+test("fromJSON Edge case: missing reference detection", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					author: { type: "ref", ref: "#user", required: true },
+				},
+				required: ["author"],
+			},
+		},
+	});
+
+	attest(ns["~infer"]).type.toString.snap(`{
+  $type: "test"
+  author: "[Reference not found: #user]"
+}`);
+});

packages/prototypey/core/tests/from-json.test.ts

···
+import { expect, test } from "vitest";
+import { fromJSON, lx } from "../lib.ts";
+
+test("fromJSON creates lexicon from JSON", () => {
+	const lexicon = fromJSON({
+		id: "app.bsky.actor.profile",
+		defs: {
+			main: {
+				type: "record",
+				key: "self",
+				record: {
+					type: "object",
+					properties: {
+						displayName: {
+							type: "string",
+							maxLength: 64,
+							maxGraphemes: 64,
+						},
+						description: {
+							type: "string",
+							maxLength: 256,
+							maxGraphemes: 256,
+						},
+					},
+				},
+			},
+		},
+	});
+
+	expect(lexicon.json).toEqual({
+		lexicon: 1,
+		id: "app.bsky.actor.profile",
+		defs: {
+			main: {
+				type: "record",
+				key: "self",
+				record: {
+					type: "object",
+					properties: {
+						displayName: {
+							type: "string",
+							maxLength: 64,
+							maxGraphemes: 64,
+						},
+						description: {
+							type: "string",
+							maxLength: 256,
+							maxGraphemes: 256,
+						},
+					},
+				},
+			},
+		},
+	});
+});
+
+test("fromJSON and lx.lexicon produce equivalent results", () => {
+	// Create using lx.lexicon
+	const viaLx = lx.lexicon("app.bsky.feed.post", {
+		main: lx.record({
+			key: "tid",
+			record: lx.object({
+				text: lx.string({ maxLength: 300, required: true }),
+				createdAt: lx.string({ format: "datetime", required: true }),
+			}),
+		}),
+	});
+
+	// Create using fromJSON
+	const viaJSON = fromJSON({
+		id: "app.bsky.feed.post",
+		defs: {
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						text: {
+							type: "string",
+							maxLength: 300,
+							required: true,
+						},
+						createdAt: {
+							type: "string",
+							format: "datetime",
+							required: true,
+						},
+					},
+					required: ["text", "createdAt"],
+				},
+			},
+		},
+	});
+
+	expect(viaLx.json).toEqual(viaJSON.json);
+});
+
+test("fromJSON supports validation", () => {
+	const lexicon = fromJSON({
+		id: "com.example.post",
+		defs: {
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						text: {
+							type: "string",
+							maxLength: 100,
+							required: true,
+						},
+					},
+					required: ["text"],
+				},
+			},
+		},
+	});
+
+	// Valid data
+	const validResult = lexicon.validate({
+		text: "Hello world",
+	});
+	expect(validResult.success).toBe(true);
+
+	// Invalid data - missing required field
+	const invalidResult = lexicon.validate({});
+	expect(invalidResult.success).toBe(false);
+
+	// Invalid data - text too long
+	const tooLongResult = lexicon.validate({
+		text: "a".repeat(101),
+	});
+	expect(tooLongResult.success).toBe(false);
+});

packages/prototypey/core/tests/infer.bench.ts

···
 import { bench } from "@ark/attest";
 import { lx } from "../lib.ts";
+import { fromJSON } from "../lib.ts";
 
 bench("infer with simple object", () => {
 	const schema = lx.lexicon("test.simple", {
···
 		}),
 	});
 	return schema["~infer"];
-}).types([741, "instantiations"]);
+}).types([748, "instantiations"]);
 
 bench("infer with complex nested structure", () => {
 	const schema = lx.lexicon("test.complex", {
···
 		}),
 	});
 	return schema["~infer"];
-}).types([1040, "instantiations"]);
+}).types([1047, "instantiations"]);
 
 bench("infer with circular reference", () => {
 	const ns = lx.lexicon("test", {
···
 		}),
 	});
 	return ns["~infer"];
-}).types([692, "instantiations"]);
+}).types([699, "instantiations"]);
 
 bench("infer with app.bsky.feed.defs lexicon", () => {
 	const schema = lx.lexicon("app.bsky.feed.defs", {
···
 		interactionShare: lx.token("User shared the feed item"),
 	});
 	return schema["~infer"];
-}).types([1285, "instantiations"]);
+}).types([1292, "instantiations"]);
+
+bench("fromJSON infer with simple object", () => {
+	const schema = fromJSON({
+		id: "test.simple",
+		defs: {
+			main: {
+				type: "object",
+				properties: {
+					id: { type: "string", required: true },
+					name: { type: "string", required: true },
+				},
+				required: ["id", "name"],
+			},
+		},
+	});
+	return schema["~infer"];
+}).types([477, "instantiations"]);
+
+bench("fromJSON infer with complex nested structure", () => {
+	const schema = fromJSON({
+		id: "test.complex",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					handle: { type: "string", required: true },
+					displayName: { type: "string" },
+				},
+				required: ["handle"],
+			},
+			reply: {
+				type: "object",
+				properties: {
+					text: { type: "string", required: true },
+					author: { type: "ref", ref: "#user", required: true },
+				},
+				required: ["text", "author"],
+			},
+			main: {
+				type: "record",
+				key: "tid",
+				record: {
+					type: "object",
+					properties: {
+						author: { type: "ref", ref: "#user", required: true },
+						replies: { type: "array", items: { type: "ref", ref: "#reply" } },
+						content: { type: "string", required: true },
+						createdAt: {
+							type: "string",
+							required: true,
+							format: "datetime",
+						},
+					},
+					required: ["author", "content", "createdAt"],
+				},
+			},
+		},
+	});
+	return schema["~infer"];
+}).types([538, "instantiations"]);
+
+bench("fromJSON infer with circular reference", () => {
+	const ns = fromJSON({
+		id: "test",
+		defs: {
+			user: {
+				type: "object",
+				properties: {
+					name: { type: "string", required: true },
+					posts: { type: "array", items: { type: "ref", ref: "#post" } },
+				},
+				required: ["name"],
+			},
+			post: {
+				type: "object",
+				properties: {
+					title: { type: "string", required: true },
+					author: { type: "ref", ref: "#user", required: true },
+				},
+				required: ["title", "author"],
+			},
+			main: {
+				type: "object",
+				properties: {
+					users: { type: "array", items: { type: "ref", ref: "#user" } },
+				},
+			},
+		},
+	});
+	return ns["~infer"];
+}).types([450, "instantiations"]);
+
+bench("fromJSON infer with app.bsky.feed.defs lexicon", () => {
+	const schema = fromJSON({
+		id: "app.bsky.feed.defs",
+		defs: {
+			viewerState: {
+				type: "object",
+				properties: {
+					repost: { type: "string", format: "at-uri" },
+					like: { type: "string", format: "at-uri" },
+					bookmarked: { type: "boolean" },
+					threadMuted: { type: "boolean" },
+					replyDisabled: { type: "boolean" },
+					embeddingDisabled: { type: "boolean" },
+					pinned: { type: "boolean" },
+				},
+			},
+			main: {
+				type: "object",
+				properties: {
+					uri: { type: "string", required: true, format: "at-uri" },
+					cid: { type: "string", required: true, format: "cid" },
+					author: {
+						type: "ref",
+						ref: "app.bsky.actor.defs#profileViewBasic",
+						required: true,
+					},
+					record: { type: "unknown", required: true },
+					embed: {
+						type: "union",
+						refs: [
+							"app.bsky.embed.images#view",
+							"app.bsky.embed.video#view",
+							"app.bsky.embed.external#view",
+							"app.bsky.embed.record#view",
+							"app.bsky.embed.recordWithMedia#view",
+						],
+					},
+					bookmarkCount: { type: "integer" },
+					replyCount: { type: "integer" },
+					repostCount: { type: "integer" },
+					likeCount: { type: "integer" },
+					quoteCount: { type: "integer" },
+					indexedAt: { type: "string", required: true, format: "datetime" },
+					viewer: { type: "ref", ref: "#viewerState" },
+					labels: {
+						type: "array",
+						items: { type: "ref", ref: "com.atproto.label.defs#label" },
+					},
+					threadgate: { type: "ref", ref: "#threadgateView" },
+				},
+				required: ["uri", "cid", "author", "record", "indexedAt"],
+			},
+			requestLess: {
+				type: "token",
+				description:
+					"Request that less content like the given feed item be shown in the feed",
+			},
+			requestMore: {
+				type: "token",
+				description:
+					"Request that more content like the given feed item be shown in the feed",
+			},
+			clickthroughItem: {
+				type: "token",
+				description: "User clicked through to the feed item",
+			},
+			clickthroughAuthor: {
+				type: "token",
+				description: "User clicked through to the author of the feed item",
+			},
+			clickthroughReposter: {
+				type: "token",
+				description: "User clicked through to the reposter of the feed item",
+			},
+			clickthroughEmbed: {
+				type: "token",
+				description:
+					"User clicked through to the embedded content of the feed item",
+			},
+			contentModeUnspecified: {
+				type: "token",
+				description: "Declares the feed generator returns any types of posts.",
+			},
+			contentModeVideo: {
+				type: "token",
+				description:
+					"Declares the feed generator returns posts containing app.bsky.embed.video embeds.",
+			},
+			interactionSeen: {
+				type: "token",
+				description: "Feed item was seen by user",
+			},
+			interactionLike: {
+				type: "token",
+				description: "User liked the feed item",
+			},
+			interactionRepost: {
+				type: "token",
+				description: "User reposted the feed item",
+			},
+			interactionReply: {
+				type: "token",
+				description: "User replied to the feed item",
+			},
+			interactionQuote: {
+				type: "token",
+				description: "User quoted the feed item",
+			},
+			interactionShare: {
+				type: "token",
+				description: "User shared the feed item",
+			},
+		},
+	});
+	return schema["~infer"];
+}).types([552, "instantiations"]);