@confect/core 9.0.0-next.2 → 9.0.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @confect/core
 
+## 9.0.0-next.3
+
+### Patch Changes
+
+- 6d85210: Resolve `FunctionImpl` / `GroupImpl` group paths via an immutable `paths` map on `Spec` instead of identity-walking the assembled tree.
+
+  ### Why
+
+  Since `9.0.0-next.1`, codegen has wrapped every parent leaf that has sibling subdirectory specs in `<parent>.addGroupAt("child", <child>)`. Because `GroupSpec.addGroupAt` is immutable, that produced a fresh object in the assembled tree, while the parent's `*.impl.ts` continued to hold a reference to the original imported leaf. The runtime resolver compared by `===`, so every such impl failed `validateImpl` with "Could not resolve group path for the provided GroupSpec." Child impls happened to work only because `GroupSpec.withName` was secretly mutating its argument in place to keep the child's identity stable — an asymmetry that was load-bearing for one half of the API and broken for the other.
+
+  ### What changed
+  - `@confect/core/Spec` carries a new `readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>` field and exposes a chainable `Spec#addPath(group, path)` builder. `add` / `addAt` / `merge` propagate `paths` unchanged; `merge` re-prefixes a node spec's entries with `"node."` to match the merged tree.
+  - `@confect/core/GroupSpec.withName` is now pure: it returns a fresh copy when the name differs and no longer rewrites the input in place. No new identity-tracking machinery is introduced.
+  - `@confect/server/FunctionImpl.make` and `GroupImpl.make` resolve their group path via `api.spec.paths.get(group)` — an O(1) map lookup instead of a tree walk — and throw a clearer error pointing at `Spec.addPath` when the spec hasn't been registered.
+  - `@confect/server/GroupPath` (the old identity-based resolver) is deleted.
+  - `@confect/cli` codegen emits one `.addPath(<binding>, "<dot.path>")` call per leaf in `_generated/spec.ts` (and `_generated/nodeSpec.ts`) so the imported leaves carry their full paths into the assembled spec value.
+
+  ### User-facing impact
+  - Spec authoring (`*.spec.ts`) and impl authoring (`*.impl.ts`) APIs are unchanged. `FunctionImpl.make(api, spec, name, handler)` and `GroupImpl.make(api, spec)` keep their exact signatures.
+  - Generated `_generated/spec.ts` (and `_generated/nodeSpec.ts`) pick up one `.addPath(...)` chain entry per leaf on the next `confect codegen` run. The shape is fully immutable — no module-load mutation, no hidden side effects.
+  - Hand-rolled tests that construct a `Spec` and pass it to `Api.make` must now also call `.addPath(spec, "dot.path")` for any group they intend to look up.
+
+  ### Fixes
+
+  This eliminates the runtime regression introduced in `9.0.0-next.1` for any project layout where a `confect/{path}.spec.ts` declares functions alongside a sibling `confect/{path}/` subdirectory of further specs.
+
 ## 9.0.0-next.2
 
 ## 9.0.0-next.1

package/dist/FunctionProvenance.d.ts

@@ -28,76 +28,76 @@ interface Convex<Args extends DefaultFunctionArgs, Returns> {
 }
 interface AnyConvex extends Convex<DefaultFunctionArgs, any> {}
 declare const FunctionProvenance: {
-  readonly Convex: Data.Case.Constructor<{
-    readonly _tag: "Convex";
-    readonly _args: DefaultFunctionArgs;
-    readonly _returns: any;
-  }, "_tag">;
   readonly Confect: Data.Case.Constructor<{
     readonly _tag: "Confect";
     readonly args: Schema.Schema.AnyNoContext;
     readonly returns: Schema.Schema.AnyNoContext;
     readonly error?: Schema.Schema.AnyNoContext;
   }, "_tag">;
-  readonly $is: <Tag extends "Convex" | "Confect">(tag: Tag) => (u: unknown) => u is Extract<{
+  readonly Convex: Data.Case.Constructor<{
     readonly _tag: "Convex";
     readonly _args: DefaultFunctionArgs;
     readonly _returns: any;
-  }, {
-    readonly _tag: Tag;
-  }> | Extract<{
+  }, "_tag">;
+  readonly $is: <Tag extends "Confect" | "Convex">(tag: Tag) => (u: unknown) => u is Extract<{
     readonly _tag: "Confect";
     readonly args: Schema.Schema.AnyNoContext;
     readonly returns: Schema.Schema.AnyNoContext;
     readonly error?: Schema.Schema.AnyNoContext;
   }, {
     readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "Convex";
+    readonly _args: DefaultFunctionArgs;
+    readonly _returns: any;
+  }, {
+    readonly _tag: Tag;
   }>;
   readonly $match: {
     <const Cases extends {
-      readonly Convex: (args: {
-        readonly _tag: "Convex";
-        readonly _args: DefaultFunctionArgs;
-        readonly _returns: any;
-      }) => any;
       readonly Confect: (args: {
         readonly _tag: "Confect";
         readonly args: Schema.Schema.AnyNoContext;
         readonly returns: Schema.Schema.AnyNoContext;
         readonly error?: Schema.Schema.AnyNoContext;
       }) => any;
-    }>(cases: Cases & { [K in Exclude<keyof Cases, "Convex" | "Confect">]: never }): (value: {
-      readonly _tag: "Convex";
-      readonly _args: DefaultFunctionArgs;
-      readonly _returns: any;
-    } | {
-      readonly _tag: "Confect";
-      readonly args: Schema.Schema.AnyNoContext;
-      readonly returns: Schema.Schema.AnyNoContext;
-      readonly error?: Schema.Schema.AnyNoContext;
-    }) => effect_Unify0.Unify<ReturnType<Cases["Convex" | "Confect"]>>;
-    <const Cases extends {
       readonly Convex: (args: {
         readonly _tag: "Convex";
         readonly _args: DefaultFunctionArgs;
         readonly _returns: any;
       }) => any;
+    }>(cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never }): (value: {
+      readonly _tag: "Confect";
+      readonly args: Schema.Schema.AnyNoContext;
+      readonly returns: Schema.Schema.AnyNoContext;
+      readonly error?: Schema.Schema.AnyNoContext;
+    } | {
+      readonly _tag: "Convex";
+      readonly _args: DefaultFunctionArgs;
+      readonly _returns: any;
+    }) => effect_Unify0.Unify<ReturnType<Cases["Confect" | "Convex"]>>;
+    <const Cases extends {
       readonly Confect: (args: {
         readonly _tag: "Confect";
         readonly args: Schema.Schema.AnyNoContext;
         readonly returns: Schema.Schema.AnyNoContext;
         readonly error?: Schema.Schema.AnyNoContext;
       }) => any;
+      readonly Convex: (args: {
+        readonly _tag: "Convex";
+        readonly _args: DefaultFunctionArgs;
+        readonly _returns: any;
+      }) => any;
     }>(value: {
-      readonly _tag: "Convex";
-      readonly _args: DefaultFunctionArgs;
-      readonly _returns: any;
-    } | {
       readonly _tag: "Confect";
       readonly args: Schema.Schema.AnyNoContext;
       readonly returns: Schema.Schema.AnyNoContext;
       readonly error?: Schema.Schema.AnyNoContext;
-    }, cases: Cases & { [K in Exclude<keyof Cases, "Convex" | "Confect">]: never }): effect_Unify0.Unify<ReturnType<Cases["Convex" | "Confect"]>>;
+    } | {
+      readonly _tag: "Convex";
+      readonly _args: DefaultFunctionArgs;
+      readonly _returns: any;
+    }, cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never }): effect_Unify0.Unify<ReturnType<Cases["Confect" | "Convex"]>>;
   };
 };
 declare const Confect: <Args extends Schema.Schema.AnyNoContext, Returns extends Schema.Schema.AnyNoContext, Error extends Schema.Schema.AnyNoContext = never>(args: Args, returns: Returns, error?: Error) => {

package/dist/FunctionProvenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FunctionProvenance.d.ts","names":[],"sources":["../src/FunctionProvenance.ts"],"mappings":";;;;;;;;KAIY,kBAAA,GAAqB,IAAA,CAAK,UAAA;EACpC,OAAA;IACE,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,YAAA;IACpB,OAAA,EAAS,MAAA,CAAO,MAAA,CAAO,YAAA;IACvB,KAAA,GAAQ,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAExB,MAAA;AAAA;AAAA,UAQe,OAAA,cACF,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,SAEnB,IAAA;EAAA,SACA,IAAA,EAAM,IAAA;EAAA,SACN,OAAA,EAAS,OAAA;EAAA,SACT,KAAA,GAAQ,KAAA;AAAA;AAAA,UAGF,UAAA,SAAmB,OAAA,CAClC,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA,UAGC,MAAA,cAAoB,mBAAA;EAAA,SAC1B,IAAA;EAAA,SACA,KAAA,EAAO,IAAA;EAAA,SACP,QAAA,EAAU,OAAA;AAAA;AAAA,UAGJ,SAAA,SAAkB,MAAA,CAAO,mBAAA;AAAA,cAE7B,kBAAA;EAAA;;oBA/BF,mBAAA;IAAA;;;;mBAND,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAAA;;oBAIf,mBAAA;IAAA;;;;;mBAND,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;IAAA;;;;;;wBAIf,mBAAA;QAAA;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;IAAA;;sBAIf,mBAAA;MAAA;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;;;;wBAIf,mBAAA;QAAA;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;IAAA;;sBAIf,mBAAA;MAAA;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;;;cAqCb,OAAA,gBACE,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA,UAE5B,IAAA,EAAM,IAAA,EACN,OAAA,EAAS,OAAA,EACT,KAAA,GAAQ,KAAA;EAAA;iBA9CA,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA;AAAA,cAoDb,MAAA,iBAAwB,mBAAA;EAAA;kBAhD1B,mBAAA;EAAA"}
+{"version":3,"file":"FunctionProvenance.d.ts","names":[],"sources":["../src/FunctionProvenance.ts"],"mappings":";;;;;;;;KAIY,kBAAA,GAAqB,IAAA,CAAK,UAAA;EACpC,OAAA;IACE,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,YAAA;IACpB,OAAA,EAAS,MAAA,CAAO,MAAA,CAAO,YAAA;IACvB,KAAA,GAAQ,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAExB,MAAA;AAAA;AAAA,UAQe,OAAA,cACF,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,SAEnB,IAAA;EAAA,SACA,IAAA,EAAM,IAAA;EAAA,SACN,OAAA,EAAS,OAAA;EAAA,SACT,KAAA,GAAQ,KAAA;AAAA;AAAA,UAGF,UAAA,SAAmB,OAAA,CAClC,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA,UAGC,MAAA,cAAoB,mBAAA;EAAA,SAC1B,IAAA;EAAA,SACA,KAAA,EAAO,IAAA;EAAA,SACP,QAAA,EAAU,OAAA;AAAA;AAAA,UAGJ,SAAA,SAAkB,MAAA,CAAO,mBAAA;AAAA,cAE7B,kBAAA;EAAA;;mBArCH,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAAA;;oBAIf,mBAAA;IAAA;;;;mBAND,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;IAAA;;;oBAIf,mBAAA;IAAA;;;;;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;MAAA;;wBAIf,mBAAA;QAAA;;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;MAAA;sBAIf,mBAAA;MAAA;;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;MAAA;;wBAIf,mBAAA;QAAA;;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;MAAA;sBAIf,mBAAA;MAAA;;;;cAiCE,OAAA,gBACE,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA,UAE5B,IAAA,EAAM,IAAA,EACN,OAAA,EAAS,OAAA,EACT,KAAA,GAAQ,KAAA;EAAA;iBA9CA,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA;AAAA,cAoDb,MAAA,iBAAwB,mBAAA;EAAA;kBAhD1B,mBAAA;EAAA"}

package/dist/GroupSpec.js

@@ -86,7 +86,12 @@ const withName = (name, group) => {
 	validateConfectFunctionIdentifier(name);
 	const group_ = group;
 	if (group_.name === name) return group_;
-	return Object.assign(group_, { name });
+	return makeProto({
+		runtime: group_.runtime,
+		name,
+		functions: group_.functions,
+		groups: group_.groups
+	});
 };
 
 //#endregion

package/dist/GroupSpec.js.map

@@ -1 +1 @@
-{"version":3,"file":"GroupSpec.js","names":[],"sources":["../src/GroupSpec.ts"],"sourcesContent":["import { Predicate, Record } from \"effect\";\nimport type * as FunctionSpec from \"./FunctionSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\nimport { validateConfectFunctionIdentifier } from \"./internal/utils\";\n\nexport const TypeId = \"@confect/core/GroupSpec\";\nexport type TypeId = typeof TypeId;\n\nexport const isGroupSpec = (u: unknown): u is AnyWithProps =>\n  Predicate.hasProperty(u, TypeId);\n\nexport interface GroupSpec<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Name_ extends string,\n  Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime> = never,\n  Groups_ extends AnyWithPropsWithRuntime<Runtime> = never,\n> {\n  readonly [TypeId]: TypeId;\n  readonly runtime: Runtime;\n  readonly name: Name_;\n  readonly functions: {\n    [FunctionName in FunctionSpec.Name<\n      FunctionSpec.AnyWithPropsWithRuntime<Runtime>\n    >]: FunctionSpec.WithName<Functions_, FunctionName>;\n  };\n  readonly groups: {\n    [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;\n  };\n\n  addFunction<Function extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>>(\n    function_: Function,\n  ): GroupSpec<Runtime, Name_, Functions_ | Function, Groups_>;\n\n  addGroup<Group extends AnyWithPropsWithRuntime<Runtime>>(\n    group: Group,\n  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | Group>;\n\n  addGroupAt<\n    const AtName extends string,\n    Group extends AnyWithPropsWithRuntime<Runtime>,\n  >(\n    name: AtName,\n    group: Group,\n  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | NamedAt<Group, AtName>>;\n}\n\nexport interface Any {\n  readonly [TypeId]: TypeId;\n}\n\nexport interface AnyWithProps extends GroupSpec<\n  RuntimeAndFunctionType.Runtime,\n  string,\n  FunctionSpec.AnyWithProps,\n  AnyWithProps\n> {}\n\nexport interface AnyWithPropsWithRuntime<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n> extends GroupSpec<\n  Runtime,\n  string,\n  FunctionSpec.AnyWithPropsWithRuntime<Runtime>,\n  AnyWithPropsWithRuntime<Runtime>\n> {}\n\nexport type Name<Group extends AnyWithProps> = Group[\"name\"];\n\nexport type Functions<Group extends AnyWithProps> =\n  Group[\"functions\"][keyof Group[\"functions\"]];\n\nexport type Groups<Group extends AnyWithProps> =\n  Group[\"groups\"][keyof Group[\"groups\"]];\n\nexport type GroupNames<Group extends AnyWithProps> = [Groups<Group>] extends [\n  never,\n]\n  ? never\n  : Name<Groups<Group>>;\n\nexport type WithName<\n  Group extends AnyWithProps,\n  Name_ extends Name<Group>,\n> = Extract<Group, { readonly name: Name_ }>;\n\n/** Assigns a segment name to a leaf group created with {@link make} for typing and refs. */\nexport type NamedAt<Group extends Any, Name_ extends string> = Omit<\n  Group,\n  \"name\"\n> & {\n  readonly name: Name_;\n};\n\nconst Proto = {\n  [TypeId]: TypeId,\n\n  addFunction<Function extends FunctionSpec.AnyWithProps>(\n    this: Any,\n    function_: Function,\n  ) {\n    const this_ = this as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: Record.set(this_.functions, function_.name, function_),\n      groups: this_.groups,\n    });\n  },\n\n  addGroup<Group extends Any>(this: Any, group: Group) {\n    const this_ = this as AnyWithProps;\n    const group_ = group as unknown as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: this_.functions,\n      groups: Record.set(this_.groups, group_.name, group_),\n    });\n  },\n\n  addGroupAt<Group extends Any>(this: Any, name: string, group: Group) {\n    const this_ = this as AnyWithProps;\n    const group_ = group as unknown as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: this_.functions,\n      groups: Record.set(this_.groups, name, withName(name, group_)),\n    });\n  },\n};\n\nconst makeProto = <\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Name_ extends string,\n  Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>,\n  Groups_ extends AnyWithPropsWithRuntime<Runtime>,\n>({\n  runtime,\n  name,\n  functions,\n  groups,\n}: {\n  runtime: Runtime;\n  name: Name_;\n  functions: Record.ReadonlyRecord<string, Functions_>;\n  groups: Record.ReadonlyRecord<string, Groups_>;\n}): GroupSpec<Runtime, Name_, Functions_, Groups_> =>\n  Object.assign(Object.create(Proto), {\n    runtime,\n    name,\n    functions,\n    groups,\n  });\n\nexport const make = (): GroupSpec<\"Convex\", \"\"> =>\n  makeProto({\n    runtime: \"Convex\",\n    name: \"\",\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n\nexport const makeAt = <const Name_ extends string>(\n  name: Name_,\n): GroupSpec<\"Convex\", Name_> => {\n  validateConfectFunctionIdentifier(name);\n\n  return makeProto({\n    runtime: \"Convex\",\n    name,\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n};\n\nexport const makeNode = (): GroupSpec<\"Node\", \"\"> =>\n  makeProto({\n    runtime: \"Node\",\n    name: \"\",\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n\nexport const makeNodeAt = <const Name_ extends string>(\n  name: Name_,\n): GroupSpec<\"Node\", Name_> => {\n  validateConfectFunctionIdentifier(name);\n\n  return makeProto({\n    runtime: \"Node\",\n    name,\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n};\n\nexport const withName = <const Name_ extends string>(\n  name: Name_,\n  group: Any,\n): AnyWithProps => {\n  validateConfectFunctionIdentifier(name);\n  const group_ = group as AnyWithProps;\n\n  if (group_.name === name) {\n    return group_;\n  }\n\n  // Keep object identity so impls can pass the same GroupSpec instance\n  // imported from a sibling `.spec.ts` into `resolveGroupPath`.\n  return Object.assign(group_, { name }) as AnyWithProps;\n};\n"],"mappings":";;;;;;;;;;;;;;AAKA,MAAa,SAAS;AAGtB,MAAa,eAAe,MAC1B,UAAU,YAAY,GAAG,OAAO;AAoFlC,MAAM,QAAQ;EACX,SAAS;CAEV,YAEE,WACA;EACA,MAAM,QAAQ;AAEd,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,OAAO,IAAI,MAAM,WAAW,UAAU,MAAM,UAAU;GACjE,QAAQ,MAAM;GACf,CAAC;;CAGJ,SAAuC,OAAc;EACnD,MAAM,QAAQ;EACd,MAAM,SAAS;AAEf,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,QAAQ,OAAO,IAAI,MAAM,QAAQ,OAAO,MAAM,OAAO;GACtD,CAAC;;CAGJ,WAAyC,MAAc,OAAc;EACnE,MAAM,QAAQ;EACd,MAAM,SAAS;AAEf,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,QAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,SAAS,MAAM,OAAO,CAAC;GAC/D,CAAC;;CAEL;AAED,MAAM,aAKJ,EACA,SACA,MACA,WACA,aAOA,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;CAClC;CACA;CACA;CACA;CACD,CAAC;AAEJ,MAAa,aACX,UAAU;CACR,SAAS;CACT,MAAM;CACN,WAAW,OAAO,OAAO;CACzB,QAAQ,OAAO,OAAO;CACvB,CAAC;AAEJ,MAAa,UACX,SAC+B;AAC/B,mCAAkC,KAAK;AAEvC,QAAO,UAAU;EACf,SAAS;EACT;EACA,WAAW,OAAO,OAAO;EACzB,QAAQ,OAAO,OAAO;EACvB,CAAC;;AAGJ,MAAa,iBACX,UAAU;CACR,SAAS;CACT,MAAM;CACN,WAAW,OAAO,OAAO;CACzB,QAAQ,OAAO,OAAO;CACvB,CAAC;AAEJ,MAAa,cACX,SAC6B;AAC7B,mCAAkC,KAAK;AAEvC,QAAO,UAAU;EACf,SAAS;EACT;EACA,WAAW,OAAO,OAAO;EACzB,QAAQ,OAAO,OAAO;EACvB,CAAC;;AAGJ,MAAa,YACX,MACA,UACiB;AACjB,mCAAkC,KAAK;CACvC,MAAM,SAAS;AAEf,KAAI,OAAO,SAAS,KAClB,QAAO;AAKT,QAAO,OAAO,OAAO,QAAQ,EAAE,MAAM,CAAC"}
+{"version":3,"file":"GroupSpec.js","names":[],"sources":["../src/GroupSpec.ts"],"sourcesContent":["import { Predicate, Record } from \"effect\";\nimport type * as FunctionSpec from \"./FunctionSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\nimport { validateConfectFunctionIdentifier } from \"./internal/utils\";\n\nexport const TypeId = \"@confect/core/GroupSpec\";\nexport type TypeId = typeof TypeId;\n\nexport const isGroupSpec = (u: unknown): u is AnyWithProps =>\n  Predicate.hasProperty(u, TypeId);\n\nexport interface GroupSpec<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Name_ extends string,\n  Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime> = never,\n  Groups_ extends AnyWithPropsWithRuntime<Runtime> = never,\n> {\n  readonly [TypeId]: TypeId;\n  readonly runtime: Runtime;\n  readonly name: Name_;\n  readonly functions: {\n    [FunctionName in FunctionSpec.Name<\n      FunctionSpec.AnyWithPropsWithRuntime<Runtime>\n    >]: FunctionSpec.WithName<Functions_, FunctionName>;\n  };\n  readonly groups: {\n    [GroupName in Name<Groups_>]: WithName<Groups_, GroupName>;\n  };\n\n  addFunction<Function extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>>(\n    function_: Function,\n  ): GroupSpec<Runtime, Name_, Functions_ | Function, Groups_>;\n\n  addGroup<Group extends AnyWithPropsWithRuntime<Runtime>>(\n    group: Group,\n  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | Group>;\n\n  addGroupAt<\n    const AtName extends string,\n    Group extends AnyWithPropsWithRuntime<Runtime>,\n  >(\n    name: AtName,\n    group: Group,\n  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | NamedAt<Group, AtName>>;\n}\n\nexport interface Any {\n  readonly [TypeId]: TypeId;\n}\n\nexport interface AnyWithProps extends GroupSpec<\n  RuntimeAndFunctionType.Runtime,\n  string,\n  FunctionSpec.AnyWithProps,\n  AnyWithProps\n> {}\n\nexport interface AnyWithPropsWithRuntime<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n> extends GroupSpec<\n  Runtime,\n  string,\n  FunctionSpec.AnyWithPropsWithRuntime<Runtime>,\n  AnyWithPropsWithRuntime<Runtime>\n> {}\n\nexport type Name<Group extends AnyWithProps> = Group[\"name\"];\n\nexport type Functions<Group extends AnyWithProps> =\n  Group[\"functions\"][keyof Group[\"functions\"]];\n\nexport type Groups<Group extends AnyWithProps> =\n  Group[\"groups\"][keyof Group[\"groups\"]];\n\nexport type GroupNames<Group extends AnyWithProps> = [Groups<Group>] extends [\n  never,\n]\n  ? never\n  : Name<Groups<Group>>;\n\nexport type WithName<\n  Group extends AnyWithProps,\n  Name_ extends Name<Group>,\n> = Extract<Group, { readonly name: Name_ }>;\n\n/** Assigns a segment name to a leaf group created with {@link make} for typing and refs. */\nexport type NamedAt<Group extends Any, Name_ extends string> = Omit<\n  Group,\n  \"name\"\n> & {\n  readonly name: Name_;\n};\n\nconst Proto = {\n  [TypeId]: TypeId,\n\n  addFunction<Function extends FunctionSpec.AnyWithProps>(\n    this: Any,\n    function_: Function,\n  ) {\n    const this_ = this as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: Record.set(this_.functions, function_.name, function_),\n      groups: this_.groups,\n    });\n  },\n\n  addGroup<Group extends Any>(this: Any, group: Group) {\n    const this_ = this as AnyWithProps;\n    const group_ = group as unknown as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: this_.functions,\n      groups: Record.set(this_.groups, group_.name, group_),\n    });\n  },\n\n  addGroupAt<Group extends Any>(this: Any, name: string, group: Group) {\n    const this_ = this as AnyWithProps;\n    const group_ = group as unknown as AnyWithProps;\n\n    return makeProto({\n      runtime: this_.runtime,\n      name: this_.name,\n      functions: this_.functions,\n      groups: Record.set(this_.groups, name, withName(name, group_)),\n    });\n  },\n};\n\nconst makeProto = <\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Name_ extends string,\n  Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>,\n  Groups_ extends AnyWithPropsWithRuntime<Runtime>,\n>({\n  runtime,\n  name,\n  functions,\n  groups,\n}: {\n  runtime: Runtime;\n  name: Name_;\n  functions: Record.ReadonlyRecord<string, Functions_>;\n  groups: Record.ReadonlyRecord<string, Groups_>;\n}): GroupSpec<Runtime, Name_, Functions_, Groups_> =>\n  Object.assign(Object.create(Proto), {\n    runtime,\n    name,\n    functions,\n    groups,\n  });\n\nexport const make = (): GroupSpec<\"Convex\", \"\"> =>\n  makeProto({\n    runtime: \"Convex\",\n    name: \"\",\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n\nexport const makeAt = <const Name_ extends string>(\n  name: Name_,\n): GroupSpec<\"Convex\", Name_> => {\n  validateConfectFunctionIdentifier(name);\n\n  return makeProto({\n    runtime: \"Convex\",\n    name,\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n};\n\nexport const makeNode = (): GroupSpec<\"Node\", \"\"> =>\n  makeProto({\n    runtime: \"Node\",\n    name: \"\",\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n\nexport const makeNodeAt = <const Name_ extends string>(\n  name: Name_,\n): GroupSpec<\"Node\", Name_> => {\n  validateConfectFunctionIdentifier(name);\n\n  return makeProto({\n    runtime: \"Node\",\n    name,\n    functions: Record.empty(),\n    groups: Record.empty(),\n  });\n};\n\nexport const withName = <const Name_ extends string>(\n  name: Name_,\n  group: Any,\n): AnyWithProps => {\n  validateConfectFunctionIdentifier(name);\n  const group_ = group as AnyWithProps;\n\n  if (group_.name === name) {\n    return group_;\n  }\n\n  return makeProto({\n    runtime: group_.runtime,\n    name,\n    functions: group_.functions,\n    groups: group_.groups,\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;AAKA,MAAa,SAAS;AAGtB,MAAa,eAAe,MAC1B,UAAU,YAAY,GAAG,OAAO;AAoFlC,MAAM,QAAQ;EACX,SAAS;CAEV,YAEE,WACA;EACA,MAAM,QAAQ;AAEd,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,OAAO,IAAI,MAAM,WAAW,UAAU,MAAM,UAAU;GACjE,QAAQ,MAAM;GACf,CAAC;;CAGJ,SAAuC,OAAc;EACnD,MAAM,QAAQ;EACd,MAAM,SAAS;AAEf,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,QAAQ,OAAO,IAAI,MAAM,QAAQ,OAAO,MAAM,OAAO;GACtD,CAAC;;CAGJ,WAAyC,MAAc,OAAc;EACnE,MAAM,QAAQ;EACd,MAAM,SAAS;AAEf,SAAO,UAAU;GACf,SAAS,MAAM;GACf,MAAM,MAAM;GACZ,WAAW,MAAM;GACjB,QAAQ,OAAO,IAAI,MAAM,QAAQ,MAAM,SAAS,MAAM,OAAO,CAAC;GAC/D,CAAC;;CAEL;AAED,MAAM,aAKJ,EACA,SACA,MACA,WACA,aAOA,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;CAClC;CACA;CACA;CACA;CACD,CAAC;AAEJ,MAAa,aACX,UAAU;CACR,SAAS;CACT,MAAM;CACN,WAAW,OAAO,OAAO;CACzB,QAAQ,OAAO,OAAO;CACvB,CAAC;AAEJ,MAAa,UACX,SAC+B;AAC/B,mCAAkC,KAAK;AAEvC,QAAO,UAAU;EACf,SAAS;EACT;EACA,WAAW,OAAO,OAAO;EACzB,QAAQ,OAAO,OAAO;EACvB,CAAC;;AAGJ,MAAa,iBACX,UAAU;CACR,SAAS;CACT,MAAM;CACN,WAAW,OAAO,OAAO;CACzB,QAAQ,OAAO,OAAO;CACvB,CAAC;AAEJ,MAAa,cACX,SAC6B;AAC7B,mCAAkC,KAAK;AAEvC,QAAO,UAAU;EACf,SAAS;EACT;EACA,WAAW,OAAO,OAAO;EACzB,QAAQ,OAAO,OAAO;EACvB,CAAC;;AAGJ,MAAa,YACX,MACA,UACiB;AACjB,mCAAkC,KAAK;CACvC,MAAM,SAAS;AAEf,KAAI,OAAO,SAAS,KAClB,QAAO;AAGT,QAAO,UAAU;EACf,SAAS,OAAO;EAChB;EACA,WAAW,OAAO;EAClB,QAAQ,OAAO;EAChB,CAAC"}

package/dist/Spec.d.ts

@@ -10,25 +10,45 @@ type TypeId = typeof TypeId;
 declare const isSpec: (u: unknown) => u is AnyWithProps;
 declare const isConvexSpec: (u: unknown) => u is AnyWithPropsWithRuntime<"Convex">;
 declare const isNodeSpec: (u: unknown) => u is AnyWithPropsWithRuntime<"Node">;
-interface Spec<Runtime$2 extends Runtime, Groups_ extends AnyWithPropsWithRuntime$1<Runtime$2> = never> {
+interface Spec<Runtime$1 extends Runtime, Groups_ extends AnyWithPropsWithRuntime$1<Runtime$1> = never> {
   readonly [TypeId]: TypeId;
-  readonly runtime: Runtime$2;
+  readonly runtime: Runtime$1;
   readonly groups: { [GroupName in Name<Groups_>]: WithName<Groups_, GroupName> };
-  add<Group extends AnyWithPropsWithRuntime$1<Runtime$2>>(group: Group): Spec<Runtime$2, Groups_ | Group>;
-  addAt<const Name$1 extends string, Group extends AnyWithPropsWithRuntime$1<Runtime$2>>(name: Name$1, group: Group): Spec<Runtime$2, Groups_ | NamedAt<Group, Name$1>>;
+  /**
+   * Mapping from an imported leaf `GroupSpec` reference to its full dot-path
+   * within this spec tree. Populated by codegen-emitted `_generated/spec.ts`
+   * via {@link Spec#addPath}; consumed by `FunctionImpl.make` /
+   * `GroupImpl.make` to resolve a spec's location without walking the tree.
+   */
+  readonly paths: ReadonlyMap<AnyWithProps$1, string>;
+  add<Group extends AnyWithPropsWithRuntime$1<Runtime$1>>(group: Group): Spec<Runtime$1, Groups_ | Group>;
+  addAt<const Name$1 extends string, Group extends AnyWithPropsWithRuntime$1<Runtime$1>>(name: Name$1, group: Group): Spec<Runtime$1, Groups_ | NamedAt<Group, Name$1>>;
+  /**
+   * Register the imported leaf `group` at `path` within this spec's path
+   * mapping. Returns a new `Spec` with one additional entry. The tree shape
+   * (`groups`) is unaffected — registration and tree assembly are
+   * independent steps, both performed by codegen in `_generated/spec.ts`.
+   *
+   * Re-registering the same group with the same path is a no-op (cheap
+   * defense for codegen watch-mode re-imports). Re-registering with a
+   * different path throws.
+   */
+  addPath(group: AnyWithProps$1, path: string): Spec<Runtime$1, Groups_>;
 }
 interface Any {
   readonly [TypeId]: TypeId;
 }
 interface AnyWithProps extends Spec<Runtime, AnyWithProps$1> {}
-interface AnyWithPropsWithRuntime<Runtime$1 extends Runtime> extends Spec<Runtime$1, AnyWithPropsWithRuntime$1<Runtime$1>> {}
+interface AnyWithPropsWithRuntime<Runtime$2 extends Runtime> extends Spec<Runtime$2, AnyWithPropsWithRuntime$1<Runtime$2>> {}
 type Groups<Spec_ extends AnyWithProps> = Spec_["groups"][keyof Spec_["groups"]];
 declare const make: () => Spec<"Convex">;
 declare const makeNode: () => Spec<"Node">;
 /**
  * Merges a Convex spec with an optional Node spec for use with `Api.make`.
  * When `nodeSpec` is provided, its groups are merged under a "node" namespace,
- * mirroring the structure used by `Refs.make`.
+ * mirroring the structure used by `Refs.make`. The node spec's `paths`
+ * entries are re-prefixed with `"node."` so they continue to identify the
+ * same leaves at their new positions in the merged tree.
  */
 declare const merge: <ConvexSpec extends AnyWithPropsWithRuntime<"Convex">, NodeSpec extends AnyWithPropsWithRuntime<"Node">>(convexSpec: ConvexSpec, nodeSpec?: NodeSpec) => AnyWithProps;
 //#endregion

package/dist/Spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Spec.d.ts","names":[],"sources":["../src/Spec.ts"],"mappings":";;;;;;;cAIa,MAAA;AAAA,KACD,MAAA,UAAgB,MAAA;AAAA,cAEf,MAAA,GAAU,CAAA,cAAa,CAAA,IAAK,YAAA;AAAA,cAG5B,YAAA,GACX,CAAA,cACC,CAAA,IAAK,uBAAA;AAAA,cAKK,UAAA,GAAc,CAAA,cAAa,CAAA,IAAK,uBAAA;AAAA,UAK5B,IAAA,mBACC,OAAA,kBACA,yBAAA,CAAkC,SAAA;EAAA,UAExC,MAAA,GAAS,MAAA;EAAA,SACV,OAAA,EAAS,SAAA;EAAA,SACT,MAAA,kBACO,IAAA,CAAe,OAAA,IAAW,QAAA,CACtC,OAAA,EACA,SAAA;EAIJ,GAAA,eAAkB,yBAAA,CAAkC,SAAA,GAClD,KAAA,EAAO,KAAA,GACN,IAAA,CAAK,SAAA,EAAS,OAAA,GAAU,KAAA;EAE3B,KAAA,4CAEgB,yBAAA,CAAkC,SAAA,GAEhD,IAAA,EAAM,MAAA,EACN,KAAA,EAAO,KAAA,GACN,IAAA,CAAK,SAAA,EAAS,OAAA,GAAU,OAAA,CAAkB,KAAA,EAAO,MAAA;AAAA;AAAA,UAGrC,GAAA;EAAA,UACL,MAAA,GAAS,MAAA;AAAA;AAAA,UAGJ,YAAA,SAAqB,IAAA,CACpC,OAAA,EACA,cAAA;AAAA,UAGe,uBAAA,mBACC,OAAA,UACR,IAAA,CAAK,SAAA,EAAS,yBAAA,CAAkC,SAAA;AAAA,KAE9C,MAAA,eAAqB,YAAA,IAC/B,KAAA,iBAAsB,KAAA;AAAA,cAuCX,IAAA,QAAW,IAAA;AAAA,cAGX,QAAA,QAAe,IAAA;;;;AAjG5B;;cAyGa,KAAA,sBACQ,uBAAA,6BACF,uBAAA,UAEjB,UAAA,EAAY,UAAA,EACZ,QAAA,GAAW,QAAA,KACV,YAAA"}
+{"version":3,"file":"Spec.d.ts","names":[],"sources":["../src/Spec.ts"],"mappings":";;;;;;;cAKa,MAAA;AAAA,KACD,MAAA,UAAgB,MAAA;AAAA,cAEf,MAAA,GAAU,CAAA,cAAa,CAAA,IAAK,YAAA;AAAA,cAG5B,YAAA,GACX,CAAA,cACC,CAAA,IAAK,uBAAA;AAAA,cAKK,UAAA,GAAc,CAAA,cAAa,CAAA,IAAK,uBAAA;AAAA,UAK5B,IAAA,mBACC,OAAA,kBACA,yBAAA,CAAkC,SAAA;EAAA,UAExC,MAAA,GAAS,MAAA;EAAA,SACV,OAAA,EAAS,SAAA;EAAA,SACT,MAAA,kBACO,IAAA,CAAe,OAAA,IAAW,QAAA,CACtC,OAAA,EACA,SAAA;;;;;;;WASK,KAAA,EAAO,WAAA,CAAY,cAAA;EAE5B,GAAA,eAAkB,yBAAA,CAAkC,SAAA,GAClD,KAAA,EAAO,KAAA,GACN,IAAA,CAAK,SAAA,EAAS,OAAA,GAAU,KAAA;EAE3B,KAAA,4CAEgB,yBAAA,CAAkC,SAAA,GAEhD,IAAA,EAAM,MAAA,EACN,KAAA,EAAO,KAAA,GACN,IAAA,CAAK,SAAA,EAAS,OAAA,GAAU,OAAA,CAAkB,KAAA,EAAO,MAAA;EAhDnC;;AACnB;;;;;AAEA;;;EAyDE,OAAA,CAAQ,KAAA,EAAO,cAAA,EAAwB,IAAA,WAAe,IAAA,CAAK,SAAA,EAAS,OAAA;AAAA;AAAA,UAGrD,GAAA;EAAA,UACL,MAAA,GAAS,MAAA;AAAA;AAAA,UAGJ,YAAA,SAAqB,IAAA,CACpC,OAAA,EACA,cAAA;AAAA,UAGe,uBAAA,mBACC,OAAA,UACR,IAAA,CAAK,SAAA,EAAS,yBAAA,CAAkC,SAAA;AAAA,KAE9C,MAAA,eAAqB,YAAA,IAC/B,KAAA,iBAAsB,KAAA;AAAA,cAwFX,IAAA,QAAW,IAAA;AAAA,cAGX,QAAA,QAAe,IAAA;;;;AA3J5B;;;;cAqKa,KAAA,sBACQ,uBAAA,6BACF,uBAAA,UAEjB,UAAA,EAAY,UAAA,EACZ,QAAA,GAAW,QAAA,KACV,YAAA"}

package/dist/Spec.js

@@ -1,6 +1,7 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { validateConfectFunctionIdentifier } from "./internal/utils.js";
 import { makeNodeAt, withName } from "./GroupSpec.js";
-import { Array, Option, Predicate, Record } from "effect";
+import { Array, Option, Predicate, Record, String } from "effect";
 
 //#region src/Spec.ts
 var Spec_exports = /* @__PURE__ */ __exportAll({
@@ -16,37 +17,68 @@ const TypeId = "@confect/core/Spec";
 const isSpec = (u) => Predicate.hasProperty(u, TypeId);
 const isConvexSpec = (u) => Predicate.hasProperty(u, TypeId) && Predicate.hasProperty(u, "runtime") && u.runtime === "Convex";
 const isNodeSpec = (u) => Predicate.hasProperty(u, TypeId) && Predicate.hasProperty(u, "runtime") && u.runtime === "Node";
+const validatePath = (path) => {
+	if (path.length === 0) throw new Error("Expected a non-empty Confect group path, but received an empty string.");
+	const segments = String.split(path, ".");
+	for (const segment of segments) {
+		if (segment.length === 0) throw new Error(`Expected a Confect group path made of dot-separated identifier segments, but received: "${path}".`);
+		validateConfectFunctionIdentifier(segment);
+	}
+};
 const Proto = {
 	[TypeId]: TypeId,
 	add(group) {
 		return makeProto({
 			runtime: this.runtime,
-			groups: Record.set(this.groups, group.name, group)
+			groups: Record.set(this.groups, group.name, group),
+			paths: this.paths
 		});
 	},
 	addAt(name, group) {
 		return makeProto({
 			runtime: this.runtime,
-			groups: Record.set(this.groups, name, withName(name, group))
+			groups: Record.set(this.groups, name, withName(name, group)),
+			paths: this.paths
+		});
+	},
+	addPath(group, path) {
+		validatePath(path);
+		const existing = this.paths.get(group);
+		if (existing !== void 0) {
+			if (existing === path) return this;
+			throw new Error(`Spec.addPath: the provided GroupSpec is already registered at "${existing}", but was re-registered at "${path}". Each GroupSpec must have at most one path.`);
+		}
+		const nextPaths = new Map(this.paths);
+		nextPaths.set(group, path);
+		return makeProto({
+			runtime: this.runtime,
+			groups: this.groups,
+			paths: nextPaths
 		});
 	}
 };
-const makeProto = ({ runtime, groups }) => Object.assign(Object.create(Proto), {
+const makeProto = ({ runtime, groups, paths }) => Object.assign(Object.create(Proto), {
 	runtime,
-	groups
+	groups,
+	paths
 });
+const emptyPaths = () => /* @__PURE__ */ new Map();
 const make = () => makeProto({
 	runtime: "Convex",
-	groups: {}
+	groups: {},
+	paths: emptyPaths()
 });
 const makeNode = () => makeProto({
 	runtime: "Node",
-	groups: {}
+	groups: {},
+	paths: emptyPaths()
 });
 /**
 * Merges a Convex spec with an optional Node spec for use with `Api.make`.
 * When `nodeSpec` is provided, its groups are merged under a "node" namespace,
-* mirroring the structure used by `Refs.make`.
+* mirroring the structure used by `Refs.make`. The node spec's `paths`
+* entries are re-prefixed with `"node."` so they continue to identify the
+* same leaves at their new positions in the merged tree.
 */
 const merge = (convexSpec, nodeSpec) => {
 	const groups = Option.fromNullable(nodeSpec).pipe(Option.map((nodeSpec_) => Array.reduce(Record.toEntries(nodeSpec_.groups), makeNodeAt("node"), (nodeGroupSpec, [name, group]) => nodeGroupSpec.addGroupAt(name, group))), Option.match({
@@ -56,9 +88,12 @@ const merge = (convexSpec, nodeSpec) => {
 			node: nodeGroup
 		})
 	}));
+	const paths = new Map(convexSpec.paths);
+	if (nodeSpec !== void 0) for (const [group, path] of nodeSpec.paths) paths.set(group, `node.${path}`);
 	return Object.assign(Object.create(Proto), {
 		runtime: "Convex",
-		groups
+		groups,
+		paths
 	});
 };
 

package/dist/Spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"Spec.js","names":["GroupSpec.withName","GroupSpec.makeNodeAt"],"sources":["../src/Spec.ts"],"sourcesContent":["import { Array, Option, Predicate, Record } from \"effect\";\nimport * as GroupSpec from \"./GroupSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\n\nexport const TypeId = \"@confect/core/Spec\";\nexport type TypeId = typeof TypeId;\n\nexport const isSpec = (u: unknown): u is AnyWithProps =>\n  Predicate.hasProperty(u, TypeId);\n\nexport const isConvexSpec = (\n  u: unknown,\n): u is AnyWithPropsWithRuntime<\"Convex\"> =>\n  Predicate.hasProperty(u, TypeId) &&\n  Predicate.hasProperty(u, \"runtime\") &&\n  u.runtime === \"Convex\";\n\nexport const isNodeSpec = (u: unknown): u is AnyWithPropsWithRuntime<\"Node\"> =>\n  Predicate.hasProperty(u, TypeId) &&\n  Predicate.hasProperty(u, \"runtime\") &&\n  u.runtime === \"Node\";\n\nexport interface Spec<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Groups_ extends GroupSpec.AnyWithPropsWithRuntime<Runtime> = never,\n> {\n  readonly [TypeId]: TypeId;\n  readonly runtime: Runtime;\n  readonly groups: {\n    [GroupName in GroupSpec.Name<Groups_>]: GroupSpec.WithName<\n      Groups_,\n      GroupName\n    >;\n  };\n\n  add<Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>>(\n    group: Group,\n  ): Spec<Runtime, Groups_ | Group>;\n\n  addAt<\n    const Name extends string,\n    Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>,\n  >(\n    name: Name,\n    group: Group,\n  ): Spec<Runtime, Groups_ | GroupSpec.NamedAt<Group, Name>>;\n}\n\nexport interface Any {\n  readonly [TypeId]: TypeId;\n}\n\nexport interface AnyWithProps extends Spec<\n  RuntimeAndFunctionType.Runtime,\n  GroupSpec.AnyWithProps\n> {}\n\nexport interface AnyWithPropsWithRuntime<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n> extends Spec<Runtime, GroupSpec.AnyWithPropsWithRuntime<Runtime>> {}\n\nexport type Groups<Spec_ extends AnyWithProps> =\n  Spec_[\"groups\"][keyof Spec_[\"groups\"]];\n\nconst Proto = {\n  [TypeId]: TypeId,\n\n  add<Group extends GroupSpec.AnyWithProps>(this: AnyWithProps, group: Group) {\n    return makeProto({\n      runtime: this.runtime,\n      groups: Record.set(this.groups, group.name, group),\n    });\n  },\n\n  addAt<Group extends GroupSpec.AnyWithProps>(\n    this: AnyWithProps,\n    name: string,\n    group: Group,\n  ) {\n    return makeProto({\n      runtime: this.runtime,\n      groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),\n    });\n  },\n};\n\nconst makeProto = <\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Groups_ extends GroupSpec.AnyWithPropsWithRuntime<Runtime>,\n>({\n  runtime,\n  groups,\n}: {\n  runtime: Runtime;\n  groups: Record.ReadonlyRecord<string, Groups_>;\n}): Spec<Runtime, Groups_> =>\n  Object.assign(Object.create(Proto), {\n    runtime,\n    groups,\n  });\n\nexport const make = (): Spec<\"Convex\"> =>\n  makeProto({ runtime: \"Convex\", groups: {} });\n\nexport const makeNode = (): Spec<\"Node\"> =>\n  makeProto({ runtime: \"Node\", groups: {} });\n\n/**\n * Merges a Convex spec with an optional Node spec for use with `Api.make`.\n * When `nodeSpec` is provided, its groups are merged under a \"node\" namespace,\n * mirroring the structure used by `Refs.make`.\n */\nexport const merge = <\n  ConvexSpec extends AnyWithPropsWithRuntime<\"Convex\">,\n  NodeSpec extends AnyWithPropsWithRuntime<\"Node\">,\n>(\n  convexSpec: ConvexSpec,\n  nodeSpec?: NodeSpec,\n): AnyWithProps => {\n  const groups = Option.fromNullable(nodeSpec).pipe(\n    Option.map((nodeSpec_) =>\n      Array.reduce(\n        Record.toEntries(nodeSpec_.groups),\n        GroupSpec.makeNodeAt(\"node\"),\n        (nodeGroupSpec, [name, group]) => nodeGroupSpec.addGroupAt(name, group),\n      ),\n    ),\n    Option.match({\n      onNone: () => convexSpec.groups,\n      onSome: (nodeGroup) => ({ ...convexSpec.groups, node: nodeGroup }),\n    }),\n  );\n\n  return Object.assign(Object.create(Proto), {\n    runtime: \"Convex\" as const,\n    groups,\n  }) as AnyWithProps;\n};\n"],"mappings":";;;;;;;;;;;;;;AAIA,MAAa,SAAS;AAGtB,MAAa,UAAU,MACrB,UAAU,YAAY,GAAG,OAAO;AAElC,MAAa,gBACX,MAEA,UAAU,YAAY,GAAG,OAAO,IAChC,UAAU,YAAY,GAAG,UAAU,IACnC,EAAE,YAAY;AAEhB,MAAa,cAAc,MACzB,UAAU,YAAY,GAAG,OAAO,IAChC,UAAU,YAAY,GAAG,UAAU,IACnC,EAAE,YAAY;AA4ChB,MAAM,QAAQ;EACX,SAAS;CAEV,IAA8D,OAAc;AAC1E,SAAO,UAAU;GACf,SAAS,KAAK;GACd,QAAQ,OAAO,IAAI,KAAK,QAAQ,MAAM,MAAM,MAAM;GACnD,CAAC;;CAGJ,MAEE,MACA,OACA;AACA,SAAO,UAAU;GACf,SAAS,KAAK;GACd,QAAQ,OAAO,IAAI,KAAK,QAAQ,MAAMA,SAAmB,MAAM,MAAM,CAAC;GACvE,CAAC;;CAEL;AAED,MAAM,aAGJ,EACA,SACA,aAKA,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;CAClC;CACA;CACD,CAAC;AAEJ,MAAa,aACX,UAAU;CAAE,SAAS;CAAU,QAAQ,EAAE;CAAE,CAAC;AAE9C,MAAa,iBACX,UAAU;CAAE,SAAS;CAAQ,QAAQ,EAAE;CAAE,CAAC;;;;;;AAO5C,MAAa,SAIX,YACA,aACiB;CACjB,MAAM,SAAS,OAAO,aAAa,SAAS,CAAC,KAC3C,OAAO,KAAK,cACV,MAAM,OACJ,OAAO,UAAU,UAAU,OAAO,EAClCC,WAAqB,OAAO,GAC3B,eAAe,CAAC,MAAM,WAAW,cAAc,WAAW,MAAM,MAAM,CACxE,CACF,EACD,OAAO,MAAM;EACX,cAAc,WAAW;EACzB,SAAS,eAAe;GAAE,GAAG,WAAW;GAAQ,MAAM;GAAW;EAClE,CAAC,CACH;AAED,QAAO,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;EACzC,SAAS;EACT;EACD,CAAC"}
+{"version":3,"file":"Spec.js","names":["GroupSpec.withName","GroupSpec.makeNodeAt"],"sources":["../src/Spec.ts"],"sourcesContent":["import { Array, Option, Predicate, Record, String } from \"effect\";\nimport * as GroupSpec from \"./GroupSpec\";\nimport type * as RuntimeAndFunctionType from \"./RuntimeAndFunctionType\";\nimport { validateConfectFunctionIdentifier } from \"./internal/utils\";\n\nexport const TypeId = \"@confect/core/Spec\";\nexport type TypeId = typeof TypeId;\n\nexport const isSpec = (u: unknown): u is AnyWithProps =>\n  Predicate.hasProperty(u, TypeId);\n\nexport const isConvexSpec = (\n  u: unknown,\n): u is AnyWithPropsWithRuntime<\"Convex\"> =>\n  Predicate.hasProperty(u, TypeId) &&\n  Predicate.hasProperty(u, \"runtime\") &&\n  u.runtime === \"Convex\";\n\nexport const isNodeSpec = (u: unknown): u is AnyWithPropsWithRuntime<\"Node\"> =>\n  Predicate.hasProperty(u, TypeId) &&\n  Predicate.hasProperty(u, \"runtime\") &&\n  u.runtime === \"Node\";\n\nexport interface Spec<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Groups_ extends GroupSpec.AnyWithPropsWithRuntime<Runtime> = never,\n> {\n  readonly [TypeId]: TypeId;\n  readonly runtime: Runtime;\n  readonly groups: {\n    [GroupName in GroupSpec.Name<Groups_>]: GroupSpec.WithName<\n      Groups_,\n      GroupName\n    >;\n  };\n  /**\n   * Mapping from an imported leaf `GroupSpec` reference to its full dot-path\n   * within this spec tree. Populated by codegen-emitted `_generated/spec.ts`\n   * via {@link Spec#addPath}; consumed by `FunctionImpl.make` /\n   * `GroupImpl.make` to resolve a spec's location without walking the tree.\n   */\n  readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;\n\n  add<Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>>(\n    group: Group,\n  ): Spec<Runtime, Groups_ | Group>;\n\n  addAt<\n    const Name extends string,\n    Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>,\n  >(\n    name: Name,\n    group: Group,\n  ): Spec<Runtime, Groups_ | GroupSpec.NamedAt<Group, Name>>;\n\n  /**\n   * Register the imported leaf `group` at `path` within this spec's path\n   * mapping. Returns a new `Spec` with one additional entry. The tree shape\n   * (`groups`) is unaffected — registration and tree assembly are\n   * independent steps, both performed by codegen in `_generated/spec.ts`.\n   *\n   * Re-registering the same group with the same path is a no-op (cheap\n   * defense for codegen watch-mode re-imports). Re-registering with a\n   * different path throws.\n   */\n  addPath(group: GroupSpec.AnyWithProps, path: string): Spec<Runtime, Groups_>;\n}\n\nexport interface Any {\n  readonly [TypeId]: TypeId;\n}\n\nexport interface AnyWithProps extends Spec<\n  RuntimeAndFunctionType.Runtime,\n  GroupSpec.AnyWithProps\n> {}\n\nexport interface AnyWithPropsWithRuntime<\n  Runtime extends RuntimeAndFunctionType.Runtime,\n> extends Spec<Runtime, GroupSpec.AnyWithPropsWithRuntime<Runtime>> {}\n\nexport type Groups<Spec_ extends AnyWithProps> =\n  Spec_[\"groups\"][keyof Spec_[\"groups\"]];\n\nconst validatePath = (path: string): void => {\n  if (path.length === 0) {\n    throw new Error(\n      \"Expected a non-empty Confect group path, but received an empty string.\",\n    );\n  }\n\n  const segments = String.split(path, \".\");\n\n  for (const segment of segments) {\n    if (segment.length === 0) {\n      throw new Error(\n        `Expected a Confect group path made of dot-separated identifier segments, but received: \"${path}\".`,\n      );\n    }\n    validateConfectFunctionIdentifier(segment);\n  }\n};\n\nconst Proto = {\n  [TypeId]: TypeId,\n\n  add<Group extends GroupSpec.AnyWithProps>(this: AnyWithProps, group: Group) {\n    return makeProto({\n      runtime: this.runtime,\n      groups: Record.set(this.groups, group.name, group),\n      paths: this.paths,\n    });\n  },\n\n  addAt<Group extends GroupSpec.AnyWithProps>(\n    this: AnyWithProps,\n    name: string,\n    group: Group,\n  ) {\n    return makeProto({\n      runtime: this.runtime,\n      groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),\n      paths: this.paths,\n    });\n  },\n\n  addPath(this: AnyWithProps, group: GroupSpec.AnyWithProps, path: string) {\n    validatePath(path);\n\n    const existing = this.paths.get(group);\n    if (existing !== undefined) {\n      if (existing === path) {\n        return this;\n      }\n      throw new Error(\n        `Spec.addPath: the provided GroupSpec is already registered at \"${existing}\", but was re-registered at \"${path}\". Each GroupSpec must have at most one path.`,\n      );\n    }\n\n    const nextPaths = new Map(this.paths);\n    nextPaths.set(group, path);\n\n    return makeProto({\n      runtime: this.runtime,\n      groups: this.groups,\n      paths: nextPaths,\n    });\n  },\n};\n\nconst makeProto = <\n  Runtime extends RuntimeAndFunctionType.Runtime,\n  Groups_ extends GroupSpec.AnyWithPropsWithRuntime<Runtime>,\n>({\n  runtime,\n  groups,\n  paths,\n}: {\n  runtime: Runtime;\n  groups: Record.ReadonlyRecord<string, Groups_>;\n  paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;\n}): Spec<Runtime, Groups_> =>\n  Object.assign(Object.create(Proto), {\n    runtime,\n    groups,\n    paths,\n  });\n\nconst emptyPaths = (): ReadonlyMap<GroupSpec.AnyWithProps, string> => new Map();\n\nexport const make = (): Spec<\"Convex\"> =>\n  makeProto({ runtime: \"Convex\", groups: {}, paths: emptyPaths() });\n\nexport const makeNode = (): Spec<\"Node\"> =>\n  makeProto({ runtime: \"Node\", groups: {}, paths: emptyPaths() });\n\n/**\n * Merges a Convex spec with an optional Node spec for use with `Api.make`.\n * When `nodeSpec` is provided, its groups are merged under a \"node\" namespace,\n * mirroring the structure used by `Refs.make`. The node spec's `paths`\n * entries are re-prefixed with `\"node.\"` so they continue to identify the\n * same leaves at their new positions in the merged tree.\n */\nexport const merge = <\n  ConvexSpec extends AnyWithPropsWithRuntime<\"Convex\">,\n  NodeSpec extends AnyWithPropsWithRuntime<\"Node\">,\n>(\n  convexSpec: ConvexSpec,\n  nodeSpec?: NodeSpec,\n): AnyWithProps => {\n  const groups = Option.fromNullable(nodeSpec).pipe(\n    Option.map((nodeSpec_) =>\n      Array.reduce(\n        Record.toEntries(nodeSpec_.groups),\n        GroupSpec.makeNodeAt(\"node\"),\n        (nodeGroupSpec, [name, group]) => nodeGroupSpec.addGroupAt(name, group),\n      ),\n    ),\n    Option.match({\n      onNone: () => convexSpec.groups,\n      onSome: (nodeGroup) => ({ ...convexSpec.groups, node: nodeGroup }),\n    }),\n  );\n\n  const paths = new Map(convexSpec.paths);\n  if (nodeSpec !== undefined) {\n    for (const [group, path] of nodeSpec.paths) {\n      paths.set(group, `node.${path}`);\n    }\n  }\n\n  return Object.assign(Object.create(Proto), {\n    runtime: \"Convex\" as const,\n    groups,\n    paths,\n  }) as AnyWithProps;\n};\n"],"mappings":";;;;;;;;;;;;;;;AAKA,MAAa,SAAS;AAGtB,MAAa,UAAU,MACrB,UAAU,YAAY,GAAG,OAAO;AAElC,MAAa,gBACX,MAEA,UAAU,YAAY,GAAG,OAAO,IAChC,UAAU,YAAY,GAAG,UAAU,IACnC,EAAE,YAAY;AAEhB,MAAa,cAAc,MACzB,UAAU,YAAY,GAAG,OAAO,IAChC,UAAU,YAAY,GAAG,UAAU,IACnC,EAAE,YAAY;AA+DhB,MAAM,gBAAgB,SAAuB;AAC3C,KAAI,KAAK,WAAW,EAClB,OAAM,IAAI,MACR,yEACD;CAGH,MAAM,WAAW,OAAO,MAAM,MAAM,IAAI;AAExC,MAAK,MAAM,WAAW,UAAU;AAC9B,MAAI,QAAQ,WAAW,EACrB,OAAM,IAAI,MACR,2FAA2F,KAAK,IACjG;AAEH,oCAAkC,QAAQ;;;AAI9C,MAAM,QAAQ;EACX,SAAS;CAEV,IAA8D,OAAc;AAC1E,SAAO,UAAU;GACf,SAAS,KAAK;GACd,QAAQ,OAAO,IAAI,KAAK,QAAQ,MAAM,MAAM,MAAM;GAClD,OAAO,KAAK;GACb,CAAC;;CAGJ,MAEE,MACA,OACA;AACA,SAAO,UAAU;GACf,SAAS,KAAK;GACd,QAAQ,OAAO,IAAI,KAAK,QAAQ,MAAMA,SAAmB,MAAM,MAAM,CAAC;GACtE,OAAO,KAAK;GACb,CAAC;;CAGJ,QAA4B,OAA+B,MAAc;AACvE,eAAa,KAAK;EAElB,MAAM,WAAW,KAAK,MAAM,IAAI,MAAM;AACtC,MAAI,aAAa,QAAW;AAC1B,OAAI,aAAa,KACf,QAAO;AAET,SAAM,IAAI,MACR,kEAAkE,SAAS,+BAA+B,KAAK,+CAChH;;EAGH,MAAM,YAAY,IAAI,IAAI,KAAK,MAAM;AACrC,YAAU,IAAI,OAAO,KAAK;AAE1B,SAAO,UAAU;GACf,SAAS,KAAK;GACd,QAAQ,KAAK;GACb,OAAO;GACR,CAAC;;CAEL;AAED,MAAM,aAGJ,EACA,SACA,QACA,YAMA,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;CAClC;CACA;CACA;CACD,CAAC;AAEJ,MAAM,mCAAgE,IAAI,KAAK;AAE/E,MAAa,aACX,UAAU;CAAE,SAAS;CAAU,QAAQ,EAAE;CAAE,OAAO,YAAY;CAAE,CAAC;AAEnE,MAAa,iBACX,UAAU;CAAE,SAAS;CAAQ,QAAQ,EAAE;CAAE,OAAO,YAAY;CAAE,CAAC;;;;;;;;AASjE,MAAa,SAIX,YACA,aACiB;CACjB,MAAM,SAAS,OAAO,aAAa,SAAS,CAAC,KAC3C,OAAO,KAAK,cACV,MAAM,OACJ,OAAO,UAAU,UAAU,OAAO,EAClCC,WAAqB,OAAO,GAC3B,eAAe,CAAC,MAAM,WAAW,cAAc,WAAW,MAAM,MAAM,CACxE,CACF,EACD,OAAO,MAAM;EACX,cAAc,WAAW;EACzB,SAAS,eAAe;GAAE,GAAG,WAAW;GAAQ,MAAM;GAAW;EAClE,CAAC,CACH;CAED,MAAM,QAAQ,IAAI,IAAI,WAAW,MAAM;AACvC,KAAI,aAAa,OACf,MAAK,MAAM,CAAC,OAAO,SAAS,SAAS,MACnC,OAAM,IAAI,OAAO,QAAQ,OAAO;AAIpC,QAAO,OAAO,OAAO,OAAO,OAAO,MAAM,EAAE;EACzC,SAAS;EACT;EACA;EACD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@confect/core",
-  "version": "9.0.0-next.2",
+  "version": "9.0.0-next.3",
   "description": "Shared specs and schemas used by all Confect packages",
   "repository": {
     "type": "git",

package/src/GroupSpec.ts

@@ -209,7 +209,10 @@ export const withName = <const Name_ extends string>(
     return group_;
   }
 
-  // Keep object identity so impls can pass the same GroupSpec instance
-  // imported from a sibling `.spec.ts` into `resolveGroupPath`.
-  return Object.assign(group_, { name }) as AnyWithProps;
+  return makeProto({
+    runtime: group_.runtime,
+    name,
+    functions: group_.functions,
+    groups: group_.groups,
+  });
 };

package/src/Spec.ts

@@ -1,6 +1,7 @@
-import { Array, Option, Predicate, Record } from "effect";
+import { Array, Option, Predicate, Record, String } from "effect";
 import * as GroupSpec from "./GroupSpec";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType";
+import { validateConfectFunctionIdentifier } from "./internal/utils";
 
 export const TypeId = "@confect/core/Spec";
 export type TypeId = typeof TypeId;
@@ -32,6 +33,13 @@ export interface Spec<
       GroupName
     >;
   };
+  /**
+   * Mapping from an imported leaf `GroupSpec` reference to its full dot-path
+   * within this spec tree. Populated by codegen-emitted `_generated/spec.ts`
+   * via {@link Spec#addPath}; consumed by `FunctionImpl.make` /
+   * `GroupImpl.make` to resolve a spec's location without walking the tree.
+   */
+  readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;
 
   add<Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>>(
     group: Group,
@@ -44,6 +52,18 @@ export interface Spec<
     name: Name,
     group: Group,
   ): Spec<Runtime, Groups_ | GroupSpec.NamedAt<Group, Name>>;
+
+  /**
+   * Register the imported leaf `group` at `path` within this spec's path
+   * mapping. Returns a new `Spec` with one additional entry. The tree shape
+   * (`groups`) is unaffected — registration and tree assembly are
+   * independent steps, both performed by codegen in `_generated/spec.ts`.
+   *
+   * Re-registering the same group with the same path is a no-op (cheap
+   * defense for codegen watch-mode re-imports). Re-registering with a
+   * different path throws.
+   */
+  addPath(group: GroupSpec.AnyWithProps, path: string): Spec<Runtime, Groups_>;
 }
 
 export interface Any {
@@ -62,6 +82,25 @@ export interface AnyWithPropsWithRuntime<
 export type Groups<Spec_ extends AnyWithProps> =
   Spec_["groups"][keyof Spec_["groups"]];
 
+const validatePath = (path: string): void => {
+  if (path.length === 0) {
+    throw new Error(
+      "Expected a non-empty Confect group path, but received an empty string.",
+    );
+  }
+
+  const segments = String.split(path, ".");
+
+  for (const segment of segments) {
+    if (segment.length === 0) {
+      throw new Error(
+        `Expected a Confect group path made of dot-separated identifier segments, but received: "${path}".`,
+      );
+    }
+    validateConfectFunctionIdentifier(segment);
+  }
+};
+
 const Proto = {
   [TypeId]: TypeId,
 
@@ -69,6 +108,7 @@ const Proto = {
     return makeProto({
       runtime: this.runtime,
       groups: Record.set(this.groups, group.name, group),
+      paths: this.paths,
     });
   },
 
@@ -80,6 +120,30 @@ const Proto = {
     return makeProto({
       runtime: this.runtime,
       groups: Record.set(this.groups, name, GroupSpec.withName(name, group)),
+      paths: this.paths,
+    });
+  },
+
+  addPath(this: AnyWithProps, group: GroupSpec.AnyWithProps, path: string) {
+    validatePath(path);
+
+    const existing = this.paths.get(group);
+    if (existing !== undefined) {
+      if (existing === path) {
+        return this;
+      }
+      throw new Error(
+        `Spec.addPath: the provided GroupSpec is already registered at "${existing}", but was re-registered at "${path}". Each GroupSpec must have at most one path.`,
+      );
+    }
+
+    const nextPaths = new Map(this.paths);
+    nextPaths.set(group, path);
+
+    return makeProto({
+      runtime: this.runtime,
+      groups: this.groups,
+      paths: nextPaths,
     });
   },
 };
@@ -90,25 +154,32 @@ const makeProto = <
 >({
   runtime,
   groups,
+  paths,
 }: {
   runtime: Runtime;
   groups: Record.ReadonlyRecord<string, Groups_>;
+  paths: ReadonlyMap<GroupSpec.AnyWithProps, string>;
 }): Spec<Runtime, Groups_> =>
   Object.assign(Object.create(Proto), {
     runtime,
     groups,
+    paths,
   });
 
+const emptyPaths = (): ReadonlyMap<GroupSpec.AnyWithProps, string> => new Map();
+
 export const make = (): Spec<"Convex"> =>
-  makeProto({ runtime: "Convex", groups: {} });
+  makeProto({ runtime: "Convex", groups: {}, paths: emptyPaths() });
 
 export const makeNode = (): Spec<"Node"> =>
-  makeProto({ runtime: "Node", groups: {} });
+  makeProto({ runtime: "Node", groups: {}, paths: emptyPaths() });
 
 /**
  * Merges a Convex spec with an optional Node spec for use with `Api.make`.
  * When `nodeSpec` is provided, its groups are merged under a "node" namespace,
- * mirroring the structure used by `Refs.make`.
+ * mirroring the structure used by `Refs.make`. The node spec's `paths`
+ * entries are re-prefixed with `"node."` so they continue to identify the
+ * same leaves at their new positions in the merged tree.
  */
 export const merge = <
   ConvexSpec extends AnyWithPropsWithRuntime<"Convex">,
@@ -131,8 +202,16 @@ export const merge = <
     }),
   );
 
+  const paths = new Map(convexSpec.paths);
+  if (nodeSpec !== undefined) {
+    for (const [group, path] of nodeSpec.paths) {
+      paths.set(group, `node.${path}`);
+    }
+  }
+
   return Object.assign(Object.create(Proto), {
     runtime: "Convex" as const,
     groups,
+    paths,
   }) as AnyWithProps;
 };