@shapeshift-labs/frontier-lang 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShapeShift Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# `@shapeshift-labs/frontier-lang`
+
+Patch-native semantic source kernel for replayable programs, merge admission, and generated TypeScript projections.
+
+This package is the first small slice of a Frontier-oriented language idea:
+
+> Source is semantic state. Editing is patches. Compilation is projection. Merge is replay plus proof/evidence.
+
+The package does not try to be a full programming language yet. It provides the runtime-neutral source graph and compiler contracts that a concrete `.frontier` parser can target later.
+
+## Install
+
+```sh
+npm install @shapeshift-labs/frontier-lang
+```
+
+The package is ESM-first and dependency-free at runtime. Local checkout examples import from `dist`, so run `npm run build` before running files under `examples/`.
+
+## Why
+
+Git merges text. Large agent swarms make concurrent semantic changes: APIs, state cells, routes, effects, migrations, tests, generated artifacts, and ownership surfaces.
+
+`frontier-lang` models those as typed graph nodes and semantic patch bundles so tooling can classify a merge before it becomes a pile of conflicting files.
+
+## Example
+
+```ts
+import {
+  actionNode,
+  classifyMerge,
+  createDocument,
+  createPatch,
+  emitTypeScript,
+  entityNode,
+  hashDocumentBase,
+  stateNode
+} from "@shapeshift-labs/frontier-lang";
+
+const todo = entityNode({
+  id: "ent_todo",
+  name: "Todo",
+  fields: [
+    { id: "field_todo_id", name: "id", type: "TodoId", key: true },
+    { id: "field_todo_title", name: "title", type: "Text", merge: { kind: "conflict" } },
+    {
+      id: "field_todo_tags",
+      name: "tags",
+      type: "Set<Text>",
+      merge: { kind: "union", law: "semilattice" }
+    }
+  ]
+});
+
+const state = stateNode({
+  id: "state_todo",
+  name: "TodoDb",
+  collections: [
+    {
+      id: "collection_todos",
+      name: "todos",
+      type: "Map<TodoId, Todo>",
+      merge: { kind: "byKey", law: "commutative" }
+    }
+  ]
+});
+
+const addTodo = actionNode({
+  id: "action_add_todo",
+  name: "addTodo",
+  input: "{ title: Text }",
+  returns: "Patch",
+  reads: ["TodoDb.todos"],
+  writes: ["TodoDb.todos"],
+  uses: ["Clock"]
+});
+
+const document = createDocument({
+  id: "mod_todo",
+  name: "TodoApp",
+  nodes: [todo, state, addTodo]
+});
+
+const baseHash = hashDocumentBase(document);
+
+const left = createPatch({
+  id: "patch_add_tags",
+  baseHash,
+  operations: [
+    {
+      op: "updateNode",
+      id: "ent_todo",
+      set: { metadata: { changedBy: "left" } },
+      touches: [{ id: "field_todo_tags", access: "write" }]
+    }
+  ],
+  evidence: [{ id: "test_tags", kind: "test", status: "passed" }]
+});
+
+const right = createPatch({
+  id: "patch_add_more_tags",
+  baseHash,
+  operations: [
+    {
+      op: "updateNode",
+      id: "ent_todo",
+      set: { metadata: { changedBy: "right" } },
+      touches: [{ id: "field_todo_tags", access: "write" }]
+    }
+  ],
+  evidence: [{ id: "test_more_tags", kind: "test", status: "passed" }]
+});
+
+console.log(classifyMerge(document, left, right).status);
+// safe-by-merge-law
+
+console.log(emitTypeScript(document));
+```
+
+## Concrete Language Shape
+
+A later parser could project source that looks like this into the graph above. This is future syntax, not a shipped parser yet:
+
+```frontier
+entity Todo @id("ent_todo") {
+  id @id("field_todo_id"): TodoId @key
+
+  title @id("field_todo_title"): Text {
+    merge conflict
+  }
+
+  tags @id("field_todo_tags"): Set<Text> {
+    merge union law semilattice
+  }
+}
+
+state TodoDb @id("state_todo") {
+  todos @id("collection_todos"): Map<TodoId, Todo> {
+    merge byKey law commutative
+  }
+}
+
+action addTodo(input: { title: Text })
+  reads TodoDb.todos
+  writes TodoDb.todos
+  uses Clock
+  returns Patch
+{
+  patch {
+    TodoDb.todos[TodoId.new()] = Todo {
+      title: input.title
+      tags: Set.empty()
+    }
+  }
+}
+```
+
+## Generated Outputs And Host Capabilities
+
+There are two separate boundaries to keep distinct:
+
+1. **JS/TS as optional projection targets.** Frontier semantic source can do the graph, replay, and merge work first, then project generated targets. This package currently ships `emitTypeScript`; JavaScript can be a later projection target or a build output derived from generated TypeScript. In this mode, JS packages are not part of the canonical source model.
+2. **JS packages as host capabilities.** Some real systems still need React, Playwright, SQLite clients, storage SDKs, crypto libraries, or browser APIs. The language can use those through explicit capability adapters such as `Network`, `Storage<T>`, `ReactView`, or `SqlClient`.
+
+The second mode should be opt-in. Importing arbitrary JS directly into semantic source would pull late-bound JavaScript behavior back into the merge problem. A better design is:
+
+Future syntax sketch:
+
+```frontier
+capability ReactView from npm("react") {
+  effects dom
+  boundary generated
+}
+```
+
+Today, the source-kernel shape for this is an effect/capability contract: actions list capabilities in `uses`, effect nodes name the capability and resources, and target nodes describe generated output. The host adapter resolves `npm:react` or browser APIs outside the canonical semantic graph.
+
+That keeps JS useful without making JavaScript the canonical language semantics.
+
+## API Surface
+
+- `createDocument`
+- `entityNode`, `stateNode`, `actionNode`, `viewNode`, `migrationNode`, `effectNode`, `moduleNode`, `targetNode`
+- `createPatch`
+- `applySemanticPatch`
+- `replayDocument`
+- `classifyMerge`
+- `emitTypeScript`
+- `stableStringify`
+- `hashSemanticValue`
+- `hashDocumentBase`
+- `validateDocument`
+
+## Status
+
+Experimental. This is the source-kernel package for proving the core loop:
+
+```txt
+semantic source graph -> patch/replay -> merge classification -> generated TypeScript
+```
+
+The next layers are a concrete `.frontier` parser, richer compiler targets, verifier hooks, and adapters to the existing Frontier package family.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { readonly [key: string]: JsonValue };
+export type JsonObject = { readonly [key: string]: JsonValue };
+export type SemanticId = string;
+export type NodeKind = "module" | "entity" | "state" | "action" | "view" | "migration" | "effect" | "target";
+export type MergePolicyKind = "conflict" | "union" | "max" | "lastWriterWins" | "byKey" | "preserveMoves" | "manual" | "custom";
+
+export interface MergePolicy {
+  readonly kind: MergePolicyKind;
+  readonly law?: "semilattice" | "commutative" | "associative" | "idempotent";
+  readonly condition?: string;
+  readonly customName?: string;
+}
+
+export interface SemanticRegion {
+  readonly id: string;
+  readonly access?: "read" | "write" | "readwrite" | "effect" | "schema" | "evidence";
+}
+
+export interface BaseNode {
+  readonly kind: NodeKind;
+  readonly id: SemanticId;
+  readonly name: string;
+  readonly parentId?: SemanticId;
+  readonly regions?: readonly SemanticRegion[];
+  readonly metadata?: JsonObject;
+}
+
+export interface CompileTarget {
+  readonly language: "typescript" | "javascript" | string;
+  readonly packageName?: string;
+  readonly emitPath?: string;
+  readonly moduleFormat?: "esm" | "commonjs";
+}
+
+export interface ModuleNode extends BaseNode {
+  readonly kind: "module";
+  readonly imports?: readonly string[];
+  readonly targets?: readonly CompileTarget[];
+}
+
+export interface FieldDeclaration {
+  readonly id: SemanticId;
+  readonly name: string;
+  readonly type: string;
+  readonly key?: boolean;
+  readonly merge?: MergePolicy;
+  readonly metadata?: JsonObject;
+}
+
+export interface EntityNode extends BaseNode {
+  readonly kind: "entity";
+  readonly fields: readonly FieldDeclaration[];
+}
+
+export interface StateCollection {
+  readonly id: SemanticId;
+  readonly name: string;
+  readonly type: string;
+  readonly merge?: MergePolicy;
+}
+
+export interface StateNode extends BaseNode {
+  readonly kind: "state";
+  readonly collections: readonly StateCollection[];
+}
+
+export interface ActionNode extends BaseNode {
+  readonly kind: "action";
+  readonly input?: string;
+  readonly returns?: string;
+  readonly reads?: readonly string[];
+  readonly writes?: readonly string[];
+  readonly uses?: readonly string[];
+  readonly throws?: readonly string[];
+  readonly body?: readonly JsonObject[];
+}
+
+export interface ViewNode extends BaseNode {
+  readonly kind: "view";
+  readonly reads?: readonly string[];
+  readonly dispatches?: readonly string[];
+}
+
+export interface MigrationNode extends BaseNode {
+  readonly kind: "migration";
+  readonly fromVersion: string;
+  readonly toVersion: string;
+  readonly changes: readonly JsonObject[];
+  readonly invariants?: readonly string[];
+}
+
+export interface EffectNode extends BaseNode {
+  readonly kind: "effect";
+  readonly capability: string;
+  readonly resources?: readonly string[];
+}
+
+export interface TargetNode extends BaseNode {
+  readonly kind: "target";
+  readonly target: CompileTarget;
+}
+
+export type SemanticNode = ModuleNode | EntityNode | StateNode | ActionNode | ViewNode | MigrationNode | EffectNode | TargetNode;
+
+export interface FrontierLangDocument {
+  readonly kind: "frontier.lang.document";
+  readonly version: 1;
+  readonly id: SemanticId;
+  readonly name: string;
+  readonly rootIds: readonly SemanticId[];
+  readonly nodes: Readonly<Record<SemanticId, SemanticNode>>;
+  readonly history?: readonly ReplayEvent[];
+  readonly metadata?: JsonObject;
+}
+
+export type SemanticPatchOperation =
+  | { readonly op: "upsertNode"; readonly node: SemanticNode; readonly touches?: readonly SemanticRegion[] }
+  | { readonly op: "removeNode"; readonly id: SemanticId; readonly touches?: readonly SemanticRegion[] }
+  | { readonly op: "renameNode"; readonly id: SemanticId; readonly name: string; readonly touches?: readonly SemanticRegion[] }
+  | { readonly op: "moveNode"; readonly id: SemanticId; readonly parentId?: SemanticId; readonly touches?: readonly SemanticRegion[] }
+  | { readonly op: "updateNode"; readonly id: SemanticId; readonly set: JsonObject; readonly touches?: readonly SemanticRegion[] }
+  | { readonly op: "addEvidence"; readonly evidence: EvidenceRecord; readonly touches?: readonly SemanticRegion[] };
+
+export interface EvidenceRecord {
+  readonly id: string;
+  readonly kind: "typecheck" | "test" | "replay" | "proof" | "trace" | "review" | "note";
+  readonly status: "passed" | "failed" | "unknown";
+  readonly path?: string;
+  readonly summary?: string;
+  readonly metadata?: JsonObject;
+}
+
+export interface SemanticPatchBundle {
+  readonly kind: "frontier.lang.patch";
+  readonly version: 1;
+  readonly id: string;
+  readonly baseHash?: string;
+  readonly targetHash?: string;
+  readonly author?: string;
+  readonly risk?: "low" | "medium" | "high" | "unknown";
+  readonly operations: readonly SemanticPatchOperation[];
+  readonly evidence?: readonly EvidenceRecord[];
+  readonly metadata?: JsonObject;
+}
+
+export interface ReplayEvent {
+  readonly id: string;
+  readonly at?: string;
+  readonly actor?: string;
+  readonly patch: SemanticPatchBundle;
+}
+
+export type MergeStatus =
+  | "safe-by-disjoint-region"
+  | "safe-by-same-change"
+  | "safe-by-merge-law"
+  | "conflict-by-overlap"
+  | "conflict-by-effect-overlap"
+  | "unknown-by-dynamic-effect"
+  | "unknown-needs-review";
+
+export interface MergeAdmission {
+  readonly status: MergeStatus;
+  readonly autoMergeable: boolean;
+  readonly reasons: readonly string[];
+  readonly overlappingNodeIds: readonly SemanticId[];
+  readonly overlappingRegions: readonly string[];
+  readonly overlappingEffects: readonly string[];
+  readonly evidence: readonly EvidenceRecord[];
+}
+
+export interface EmitTypeScriptOptions {
+  readonly banner?: string;
+  readonly includeRuntimeTypes?: boolean;
+}
+
+export declare function moduleNode(input: Omit<ModuleNode, "kind">): ModuleNode;
+export declare function entityNode(input: Omit<EntityNode, "kind">): EntityNode;
+export declare function stateNode(input: Omit<StateNode, "kind">): StateNode;
+export declare function actionNode(input: Omit<ActionNode, "kind">): ActionNode;
+export declare function viewNode(input: Omit<ViewNode, "kind">): ViewNode;
+export declare function migrationNode(input: Omit<MigrationNode, "kind">): MigrationNode;
+export declare function effectNode(input: Omit<EffectNode, "kind">): EffectNode;
+export declare function targetNode(input: Omit<TargetNode, "kind">): TargetNode;
+export declare function createPatch(input: Omit<SemanticPatchBundle, "kind" | "version">): SemanticPatchBundle;
+export declare function createDocument(input: {
+  readonly id: SemanticId;
+  readonly name: string;
+  readonly nodes: readonly SemanticNode[];
+  readonly rootIds?: readonly SemanticId[];
+  readonly history?: readonly ReplayEvent[];
+  readonly metadata?: JsonObject;
+}): FrontierLangDocument;
+export declare function stableStringify(value: unknown): string;
+export declare function hashSemanticValue(value: unknown): string;
+export declare function hashDocumentBase(document: FrontierLangDocument): string;
+export declare function validateDocument(document: FrontierLangDocument): readonly string[];
+export declare function applySemanticPatch(document: FrontierLangDocument, patch: SemanticPatchBundle, event?: ReplayEvent): FrontierLangDocument;
+export declare function replayDocument(initial: FrontierLangDocument, events: readonly ReplayEvent[]): FrontierLangDocument;
+export declare function classifyMerge(base: FrontierLangDocument, left: SemanticPatchBundle, right: SemanticPatchBundle): MergeAdmission;
+export declare function emitTypeScript(document: FrontierLangDocument, options?: EmitTypeScriptOptions): string;

package/dist/index.js

@@ -0,0 +1,608 @@
+export function moduleNode(input) {
+  return { ...input, kind: "module" };
+}
+
+export function entityNode(input) {
+  return { ...input, kind: "entity" };
+}
+
+export function stateNode(input) {
+  return { ...input, kind: "state" };
+}
+
+export function actionNode(input) {
+  return { ...input, kind: "action" };
+}
+
+export function viewNode(input) {
+  return { ...input, kind: "view" };
+}
+
+export function migrationNode(input) {
+  return { ...input, kind: "migration" };
+}
+
+export function effectNode(input) {
+  return { ...input, kind: "effect" };
+}
+
+export function targetNode(input) {
+  return { ...input, kind: "target" };
+}
+
+export function createPatch(input) {
+  return {
+    ...input,
+    kind: "frontier.lang.patch",
+    version: 1
+  };
+}
+
+export function createDocument(input) {
+  const nodes = {};
+  for (const node of input.nodes) {
+    if (nodes[node.id]) {
+      throw new Error(`Duplicate semantic node id: ${node.id}`);
+    }
+    nodes[node.id] = node;
+  }
+
+  return {
+    kind: "frontier.lang.document",
+    version: 1,
+    id: input.id,
+    name: input.name,
+    rootIds: input.rootIds ?? input.nodes.filter((node) => !node.parentId).map((node) => node.id),
+    nodes,
+    history: input.history,
+    metadata: input.metadata
+  };
+}
+
+export function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+
+  const entries = Object.entries(value)
+    .filter(([, item]) => item !== undefined)
+    .sort(([left], [right]) => ordinalCompare(left, right));
+
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+}
+
+export function hashSemanticValue(value) {
+  const serialized = stableStringify(value);
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < serialized.length; index += 1) {
+    hash ^= serialized.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+export function hashDocumentBase(document) {
+  return hashSemanticValue(stripHistory(document));
+}
+
+export function validateDocument(document) {
+  const issues = [];
+  const rootSet = new Set();
+
+  for (const rootId of document.rootIds) {
+    if (rootSet.has(rootId)) {
+      issues.push(`Duplicate root node: ${rootId}`);
+    }
+    rootSet.add(rootId);
+    if (!document.nodes[rootId]) {
+      issues.push(`Missing root node: ${rootId}`);
+    }
+  }
+
+  for (const [nodeId, node] of Object.entries(document.nodes)) {
+    if (node.id !== nodeId) {
+      issues.push(`Node record key ${nodeId} does not match node id ${node.id}`);
+    }
+
+    if (node.parentId && !document.nodes[node.parentId]) {
+      issues.push(`Node ${node.id} references missing parent ${node.parentId}`);
+    }
+
+    if (node.parentId === node.id) {
+      issues.push(`Node ${node.id} cannot be its own parent`);
+    }
+
+    if (!node.parentId && !rootSet.has(node.id)) {
+      issues.push(`Parentless node ${node.id} is missing from rootIds`);
+    }
+
+    if (node.parentId && rootSet.has(node.id)) {
+      issues.push(`Node ${node.id} has a parent and cannot be a root`);
+    }
+
+    if (hasAncestorCycle(document.nodes, node.id)) {
+      issues.push(`Node ${node.id} is part of a parent cycle`);
+    }
+
+    if (node.kind === "entity") {
+      const fieldIds = new Set();
+      for (const field of node.fields) {
+        if (fieldIds.has(field.id)) {
+          issues.push(`Entity ${node.id} has duplicate field id ${field.id}`);
+        }
+        fieldIds.add(field.id);
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function applySemanticPatch(document, patch, event) {
+  if (patch.baseHash && patch.baseHash !== hashDocumentBase(document)) {
+    throw new Error(`Patch ${patch.id} base hash does not match document`);
+  }
+
+  let nodes = { ...document.nodes };
+  let rootIds = [...document.rootIds];
+
+  for (const operation of patch.operations) {
+    switch (operation.op) {
+      case "upsertNode": {
+        nodes = { ...nodes, [operation.node.id]: operation.node };
+        if (!operation.node.parentId && !rootIds.includes(operation.node.id)) {
+          rootIds = [...rootIds, operation.node.id];
+        }
+        break;
+      }
+      case "removeNode": {
+        const nextNodes = { ...nodes };
+        delete nextNodes[operation.id];
+        nodes = nextNodes;
+        rootIds = rootIds.filter((id) => id !== operation.id);
+        break;
+      }
+      case "renameNode": {
+        const node = requireNode(nodes, operation.id);
+        nodes = { ...nodes, [operation.id]: { ...node, name: operation.name } };
+        break;
+      }
+      case "moveNode": {
+        const node = requireNode(nodes, operation.id);
+        nodes = { ...nodes, [operation.id]: { ...node, parentId: operation.parentId } };
+        rootIds = operation.parentId
+          ? rootIds.filter((id) => id !== operation.id)
+          : unique([...rootIds, operation.id]);
+        break;
+      }
+      case "updateNode": {
+        if (
+          Object.hasOwn(operation.set, "id") ||
+          Object.hasOwn(operation.set, "kind") ||
+          Object.hasOwn(operation.set, "parentId")
+        ) {
+          throw new Error(`Patch ${patch.id} cannot update semantic node identity, kind, or parent`);
+        }
+        const node = requireNode(nodes, operation.id);
+        nodes = { ...nodes, [operation.id]: { ...node, ...operation.set } };
+        break;
+      }
+      case "addEvidence":
+        break;
+      default:
+        throw new Error(`Unexpected operation: ${operation.op}`);
+    }
+  }
+
+  const next = {
+    ...document,
+    rootIds,
+    nodes
+  };
+
+  const issues = validateDocument(next);
+  if (issues.length > 0) {
+    throw new Error(`Invalid document after patch ${patch.id}: ${issues.join("; ")}`);
+  }
+
+  if (patch.targetHash && patch.targetHash !== hashDocumentBase(next)) {
+    throw new Error(`Patch ${patch.id} target hash does not match result`);
+  }
+
+  return {
+    ...next,
+    history: [
+      ...(document.history ?? []),
+      event ?? {
+        id: `event:${patch.id}`,
+        patch
+      }
+    ]
+  };
+}
+
+export function replayDocument(initial, events) {
+  return events.reduce((document, event) => applySemanticPatch(document, event.patch, event), initial);
+}
+
+export function classifyMerge(base, left, right) {
+  const baseHash = hashDocumentBase(base);
+  const reasons = [];
+
+  if (left.baseHash && left.baseHash !== baseHash) {
+    reasons.push(`Left patch base hash ${left.baseHash} does not match current base ${baseHash}`);
+  }
+  if (right.baseHash && right.baseHash !== baseHash) {
+    reasons.push(`Right patch base hash ${right.baseHash} does not match current base ${baseHash}`);
+  }
+
+  const leftSummary = summarizePatch(left);
+  const rightSummary = summarizePatch(right);
+  const overlappingNodeIds = intersection(leftSummary.nodeIds, rightSummary.nodeIds);
+  const overlappingRegions = intersection(leftSummary.regions, rightSummary.regions);
+  const overlappingEffects = intersection(leftSummary.effects, rightSummary.effects);
+  const evidence = [...(left.evidence ?? []), ...(right.evidence ?? [])];
+  const failedEvidence = evidence.filter((record) => record.status === "failed");
+
+  if (reasons.length > 0) {
+    return {
+      status: "unknown-needs-review",
+      autoMergeable: false,
+      reasons,
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  if (failedEvidence.length > 0) {
+    return {
+      status: "unknown-needs-review",
+      autoMergeable: false,
+      reasons: [`Failed evidence prevents auto-merge: ${failedEvidence.map((record) => record.id).join(", ")}`],
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  if (stableStringify(left.operations) === stableStringify(right.operations)) {
+    return {
+      status: "safe-by-same-change",
+      autoMergeable: true,
+      reasons: ["Both patches contain the same semantic operations."],
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  const dynamicEffects = new Set(["dynamic", "eval", "unsafeEval", "ffi", "reflection", "proxy"]);
+  const hasDynamic = [...leftSummary.effects, ...rightSummary.effects].some((effect) =>
+    dynamicEffects.has(effect)
+  );
+  if (hasDynamic) {
+    return {
+      status: "unknown-by-dynamic-effect",
+      autoMergeable: false,
+      reasons: ["At least one patch touches a dynamic or opaque effect boundary."],
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  if (overlappingEffects.length > 0) {
+    return {
+      status: "conflict-by-effect-overlap",
+      autoMergeable: false,
+      reasons: [`Both patches touch effect(s): ${overlappingEffects.join(", ")}`],
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  if (overlappingNodeIds.length > 0 || overlappingRegions.length > 0) {
+    const laws = collectMergeLaws(base, [...overlappingNodeIds, ...overlappingRegions]);
+    if (laws.length > 0 && laws.every((law) => law === "semilattice" || law === "commutative")) {
+      return withReplayGate(base, left, right, {
+        status: "safe-by-merge-law",
+        autoMergeable: true,
+        reasons: [`Overlaps are covered by merge law(s): ${unique(laws).join(", ")}`],
+        overlappingNodeIds,
+        overlappingRegions,
+        overlappingEffects,
+        evidence
+      });
+    }
+
+    return {
+      status: "conflict-by-overlap",
+      autoMergeable: false,
+      reasons: ["Patches touch the same semantic node or region without a known merge law."],
+      overlappingNodeIds,
+      overlappingRegions,
+      overlappingEffects,
+      evidence
+    };
+  }
+
+  return withReplayGate(base, left, right, {
+    status: "safe-by-disjoint-region",
+    autoMergeable: true,
+    reasons: ["Patches touch disjoint semantic nodes, regions, and effects."],
+    overlappingNodeIds,
+    overlappingRegions,
+    overlappingEffects,
+    evidence
+  });
+}
+
+export function emitTypeScript(document, options = {}) {
+  const lines = [];
+  const banner = options.banner ?? "Generated by @shapeshift-labs/frontier-lang.";
+  lines.push(`// ${banner}`);
+  lines.push("");
+
+  if (options.includeRuntimeTypes ?? true) {
+    lines.push("export type FrontierPatchOperation =");
+    lines.push("  | { op: 'set'; path: string; value: unknown }");
+    lines.push("  | { op: 'remove'; path: string }");
+    lines.push("  | { op: 'insert'; path: string; value: unknown }");
+    lines.push("  | { op: 'merge'; path: string; value: unknown };");
+    lines.push("");
+  }
+
+  for (const node of Object.values(document.nodes)) {
+    if (node.kind === "entity") {
+      lines.push(`export interface ${safeIdentifier(node.name)} {`);
+      for (const field of node.fields) {
+        lines.push(`  ${safeIdentifier(field.name)}: ${toTypeScriptType(field.type)};`);
+      }
+      lines.push("}");
+      lines.push("");
+    }
+  }
+
+  for (const node of Object.values(document.nodes)) {
+    if (node.kind === "action") {
+      const inputType = node.input ? toTypeScriptType(node.input) : "unknown";
+      const returnType = node.returns ? toTypeScriptType(node.returns) : "FrontierPatchOperation[]";
+      lines.push(`export function ${safeIdentifier(node.name)}(`);
+      lines.push("  state: unknown,");
+      lines.push(`  input: ${inputType},`);
+      lines.push("  env: Record<string, unknown> = {}");
+      lines.push(`): ${returnType} {`);
+      lines.push("  void state;");
+      lines.push("  void input;");
+      lines.push("  void env;");
+      lines.push(`  return [] as ${returnType};`);
+      lines.push("}");
+      lines.push("");
+    }
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function stripHistory(document) {
+  const { history: _history, ...rest } = document;
+  return rest;
+}
+
+function requireNode(nodes, id) {
+  const node = nodes[id];
+  if (!node) {
+    throw new Error(`Unknown semantic node id: ${id}`);
+  }
+  return node;
+}
+
+function hasAncestorCycle(nodes, startId) {
+  const seen = new Set();
+  let current = nodes[startId];
+  while (current?.parentId) {
+    if (seen.has(current.parentId)) {
+      return true;
+    }
+    seen.add(current.parentId);
+    current = nodes[current.parentId];
+  }
+  return false;
+}
+
+function summarizePatch(patch) {
+  const nodeIds = [];
+  const regions = [];
+  const effects = [];
+
+  for (const operation of patch.operations) {
+    if ("id" in operation && typeof operation.id === "string") {
+      nodeIds.push(operation.id);
+    }
+    if (operation.op === "upsertNode") {
+      nodeIds.push(operation.node.id);
+      for (const region of operation.node.regions ?? []) {
+        regions.push(region.id);
+      }
+      if (operation.node.kind === "action") {
+        effects.push(...(operation.node.uses ?? []));
+      }
+      if (operation.node.kind === "effect") {
+        effects.push(operation.node.capability);
+      }
+    }
+    if (operation.op === "updateNode") {
+      if (Array.isArray(operation.set.uses)) {
+        effects.push(...operation.set.uses.filter((value) => typeof value === "string"));
+      }
+      if (typeof operation.set.capability === "string") {
+        effects.push(operation.set.capability);
+      }
+      if (Array.isArray(operation.set.regions)) {
+        for (const region of operation.set.regions) {
+          if (region && typeof region === "object" && region.access === "effect" && typeof region.id === "string") {
+            effects.push(region.id);
+          }
+        }
+      }
+    }
+
+    for (const region of operation.touches ?? []) {
+      regions.push(region.id);
+      if (region.access === "effect") {
+        effects.push(region.id);
+      }
+    }
+  }
+
+  return {
+    nodeIds: unique(nodeIds),
+    regions: unique(regions),
+    effects: unique(effects)
+  };
+}
+
+function withReplayGate(base, left, right, admission) {
+  if (!admission.autoMergeable) {
+    return admission;
+  }
+
+  try {
+    const leftForReplay = stripPatchAdmissionHashes(left);
+    const rightForReplay = stripPatchAdmissionHashes(right);
+    const leftThenRight = applySemanticPatch(applySemanticPatch(base, leftForReplay), rightForReplay);
+    const rightThenLeft = applySemanticPatch(applySemanticPatch(base, rightForReplay), leftForReplay);
+    const leftHash = hashDocumentBase(leftThenRight);
+    const rightHash = hashDocumentBase(rightThenLeft);
+    if (leftHash !== rightHash) {
+      return {
+        ...admission,
+        status: "unknown-needs-review",
+        autoMergeable: false,
+        reasons: [
+          ...admission.reasons,
+          `Replay order is not commutative: left-right ${leftHash}, right-left ${rightHash}`
+        ]
+      };
+    }
+    return admission;
+  } catch (error) {
+    return {
+      ...admission,
+      status: "unknown-needs-review",
+      autoMergeable: false,
+      reasons: [...admission.reasons, `Replay gate failed: ${error instanceof Error ? error.message : String(error)}`]
+    };
+  }
+}
+
+function stripPatchAdmissionHashes(patch) {
+  const { baseHash: _baseHash, targetHash: _targetHash, ...rest } = patch;
+  return rest;
+}
+
+function collectMergeLaws(document, overlaps) {
+  const overlapSet = new Set(overlaps);
+  const laws = [];
+
+  for (const node of Object.values(document.nodes)) {
+    if (node.kind === "entity") {
+      for (const field of node.fields) {
+        if (overlapSet.has(field.id) || overlapSet.has(`${node.name}.${field.name}`)) {
+          if (field.merge?.law) {
+            laws.push(field.merge.law);
+          }
+        }
+      }
+    }
+    if (node.kind === "state") {
+      for (const collection of node.collections) {
+        if (overlapSet.has(collection.id) || overlapSet.has(`${node.name}.${collection.name}`)) {
+          if (collection.merge?.law) {
+            laws.push(collection.merge.law);
+          }
+        }
+      }
+    }
+  }
+
+  return laws;
+}
+
+function intersection(left, right) {
+  const rightSet = new Set(right);
+  return unique(left.filter((item) => rightSet.has(item)));
+}
+
+function unique(items) {
+  return [...new Set(items)];
+}
+
+function ordinalCompare(left, right) {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function safeIdentifier(name) {
+  const identifier = name.replace(/[^A-Za-z0-9_$]/g, "_");
+  if (/^[A-Za-z_$]/.test(identifier)) {
+    return identifier;
+  }
+  return `_${identifier}`;
+}
+
+function toTypeScriptType(type) {
+  const primitive = {
+    Text: "string",
+    String: "string",
+    Bool: "boolean",
+    Boolean: "boolean",
+    Int: "number",
+    Float: "number",
+    Number: "number",
+    Instant: "string",
+    Json: "unknown",
+    Patch: "FrontierPatchOperation[]"
+  };
+
+  if (primitive[type]) {
+    return primitive[type];
+  }
+
+  const setMatch = /^Set<(.+)>$/.exec(type);
+  if (setMatch) {
+    return `ReadonlySet<${toTypeScriptType(setMatch[1].trim())}>`;
+  }
+
+  const listMatch = /^(List|MoveList)<(.+)>$/.exec(type);
+  if (listMatch) {
+    return `readonly ${toTypeScriptType(listMatch[2].trim())}[]`;
+  }
+
+  const mapMatch = /^Map<(.+),(.+)>$/.exec(type);
+  if (mapMatch) {
+    return `ReadonlyMap<${toTypeScriptType(mapMatch[1].trim())}, ${toTypeScriptType(mapMatch[2].trim())}>`;
+  }
+
+  if (/^\{.*\}$/.test(type)) {
+    return "Record<string, unknown>";
+  }
+
+  return safeIdentifier(type);
+}

package/examples/todo.mjs

@@ -0,0 +1,83 @@
+import {
+  actionNode,
+  classifyMerge,
+  createDocument,
+  createPatch,
+  emitTypeScript,
+  entityNode,
+  hashDocumentBase,
+  stateNode
+} from "../dist/index.js";
+
+const todo = entityNode({
+  id: "ent_todo",
+  name: "Todo",
+  fields: [
+    { id: "field_todo_id", name: "id", type: "TodoId", key: true },
+    { id: "field_todo_title", name: "title", type: "Text", merge: { kind: "conflict" } },
+    {
+      id: "field_todo_tags",
+      name: "tags",
+      type: "Set<Text>",
+      merge: { kind: "union", law: "semilattice" }
+    }
+  ]
+});
+
+const state = stateNode({
+  id: "state_todo",
+  name: "TodoDb",
+  collections: [
+    {
+      id: "collection_todos",
+      name: "todos",
+      type: "Map<TodoId, Todo>",
+      merge: { kind: "byKey", law: "commutative" }
+    }
+  ]
+});
+
+const addTodo = actionNode({
+  id: "action_add_todo",
+  name: "addTodo",
+  input: "{ title: Text }",
+  returns: "Patch",
+  reads: ["TodoDb.todos"],
+  writes: ["TodoDb.todos"],
+  uses: ["Clock"]
+});
+
+const document = createDocument({
+  id: "mod_todo",
+  name: "TodoApp",
+  nodes: [todo, state, addTodo]
+});
+
+const baseHash = hashDocumentBase(document);
+const left = createPatch({
+  id: "patch_left_tags",
+  baseHash,
+  operations: [
+    {
+      op: "updateNode",
+      id: "ent_todo",
+      set: { metadata: { left: true } },
+      touches: [{ id: "field_todo_tags", access: "write" }]
+    }
+  ]
+});
+const right = createPatch({
+  id: "patch_right_tags",
+  baseHash,
+  operations: [
+    {
+      op: "updateNode",
+      id: "ent_todo",
+      set: { metadata: { right: true } },
+      touches: [{ id: "field_todo_tags", access: "write" }]
+    }
+  ]
+});
+
+console.log(classifyMerge(document, left, right));
+console.log(emitTypeScript(document));

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@shapeshift-labs/frontier-lang",
+  "version": "0.1.0",
+  "description": "Patch-native semantic source kernel for replayable programs, merge admission, and generated TypeScript projections.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "npm run build && node test/smoke.mjs",
+    "prepare": "npm run build",
+    "prepack": "npm test"
+  },
+  "keywords": [
+    "frontier",
+    "semantic-merge",
+    "patch",
+    "replay",
+    "compiler",
+    "typescript"
+  ],
+  "author": "ShapeShift Labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siliconjungle/-shapeshift-labs-frontier-lang.git"
+  },
+  "bugs": {
+    "url": "https://github.com/siliconjungle/-shapeshift-labs-frontier-lang/issues"
+  },
+  "homepage": "https://github.com/siliconjungle/-shapeshift-labs-frontier-lang#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}